agent-auth-cli

Agent Auth CLI

Agent Auth プロバイダーとやり取りするための auth-agent CLI を利用できます。エージェント認証に関する操作では、生の HTTP リクエストを送信したり、独自のコードを記述したりせず、必ず CLI を使用してください。

バイナリ

CLI のバイナリは auth-agent（パッケージ：@auth/agent-cli）です。グローバルにインストールされていない場合は、npx @auth/agent-cli を実行してください。

ワークフロー

プロバイダーを操作する際は、次の順序に従ってください。

1. プロバイダーを検出または検索する

# If you have the provider URL
auth-agent discover https://api.example.com

# If you need to search by intent
auth-agent search "deploy web apps"

# List already-known providers
auth-agent providers

• discover は /.well-known/agent-configuration ドキュメントを取得し、プロバイダーをキャッシュします。
• search はディレクトリを検索し、一致するプロバイダーを返します。
• 接続する前に、必ず検出または検索してください。

2. 機能を確認する

# List all capabilities for a provider
auth-agent capabilities --provider https://api.example.com

# Filter by query
auth-agent capabilities --provider https://api.example.com --query "transfer"

# Get full definition with input schema
auth-agent describe transfer_money --provider https://api.example.com

• 機能を実行する前に、必ず describe を実行して、必要な入力スキーマと制約を確認してください。
• 接続済みの場合は、--agent-id <id> を渡すと、付与されている機能を確認できます。

3. エージェントを接続する

# Basic connection with specific capabilities
auth-agent connect --provider https://api.example.com \
  --capabilities read_data transfer_money \
  --name my-agent

# With constraints on capability arguments
auth-agent connect --provider https://api.example.com \
  --capabilities read_data transfer_money \
  --constraints '{"transfer_money":{"amount":{"max":1000}}}' \
  --name constrained-agent

# Autonomous mode (no user association)
auth-agent connect --provider https://api.example.com \
  --capabilities read_data \
  --mode autonomous

# With CIBA approval (backchannel, sends notification to user)
auth-agent connect --provider https://api.example.com \
  --capabilities read_data \
  --preferred-method ciba \
  --login-hint [email protected]

• 返された agent_id を保存してください。以降のすべての操作で必要です。
• 承認が必要な場合、CLI はブラウザーを開くか、承認 URL を表示します。ブラウザーを開かないようにするには、--no-browser を渡してください。
• 既存の接続があっても新しい接続を作成するには、--force-new を使用してください。

4. ステータスを確認する

auth-agent status <agent-id>

• エージェントのステータス（pending_approval、active、expired、revoked）、付与された機能、制約が表示されます。
• 接続後に実行して、エージェントが承認されたことを確認してください。

5. 機能を実行する

auth-agent execute <agent-id> transfer_money \
  --args '{"amount": 50, "to": "alice"}'

• --args フラグには、機能の入力スキーマに一致する JSON 文字列を指定します。
• 必要な引数を確認するため、機能を実行する前に必ず describe を実行してください。

6. 追加の機能をリクエストする

auth-agent request <agent-id> \
  --capabilities admin_panel \
  --constraints '{"admin_panel":{"scope":{"in":["read","write"]}}}' \
  --reason "Need admin access for deployment"

7. ライフサイクルを管理する

# Disconnect (revoke) an agent
auth-agent disconnect <agent-id>

# Reactivate an expired agent
auth-agent reactivate <agent-id>

# View stored connection details
auth-agent connection <agent-id>

# List all connections for a provider
auth-agent connections <issuer-url>

8. キーをローテーションする

# Rotate an agent's keypair
auth-agent rotate-agent-key <agent-id>

# Rotate the host keypair for a provider
auth-agent rotate-host-key <issuer-url>

9. ホストを登録する

auth-agent enroll-host --provider https://api.example.com --token <enrollment-token> --name "My Device"

10. JWT に手動で署名する

# Sign an agent JWT (for use with external HTTP calls)
auth-agent sign <agent-id>

# Scope to specific capabilities
auth-agent sign <agent-id> --capabilities transfer_money read_data

グローバルフラグ

フラグ	環境変数	説明
--storage-dir <path>	AGENT_AUTH_STORAGE_DIR	ストレージディレクトリ（デフォルト：~/.agent-auth）
--directory-url <url>	AGENT_AUTH_DIRECTORY_URL	プロバイダー検索用のディレクトリ URL
--host-name <name>	AGENT_AUTH_HOST_NAME	識別用のホスト名
--no-browser	AGENT_AUTH_NO_BROWSER=1	承認 URL 用のブラウザー起動を抑制
--url <urls...>	AGENT_AUTH_URLS	起動時に自動検出するプロバイダー URL

重要なルール

• Agent Auth のエンドポイントに生の HTTP リクエストを送信しないでください。 必ず CLI を使用してください。
• 接続する前に、必ず検出してください。 CLI でプロバイダーの設定をローカルにキャッシュする必要があります。
• 実行する前に、必ず内容を確認してください。 正しい引数を渡せるよう、入力スキーマを確認してください。
• 接続後にステータスを確認してください。 エージェントが有効になる前に、ユーザーの承認が必要な場合があります。
• エージェント ID を保存してください。 execute、status、request、disconnect など、すべての操作で必要です。
• 接続時に制約を設定して、エージェントが実行できる操作を制限してください。 これはセキュリティのベストプラクティスです。
• 本番環境では、AGENT_AUTH_ENCRYPTION_KEY を設定して、~/.agent-auth/ に保存される秘密鍵を暗号化してください。

ストレージ

接続、鍵、プロバイダー設定は、デフォルトで ~/.agent-auth/ に保存されます。

• host.json — ホストの ID と鍵ペア
• agents/<agent-id>.json — エージェントの接続
• providers/<encoded-issuer>.json — キャッシュされたプロバイダー設定