agent-auth-cli

Agent Auth CLI

你可以使用 auth-agent CLI 与 Agent Auth 提供方交互。进行任何 Agent 身份验证操作时，始终优先使用 CLI，而不是直接发送 HTTP 请求或编写自定义代码。

二进制文件

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. 连接 Agent

# 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>

• 显示 Agent 状态（pending_approval、active、expired、revoked）、已授予的功能和约束。
• 连接后运行此命令，确认 Agent 已获批准。

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 需要在本地缓存提供方配置。
• **执行前始终先进行描述。**检查输入架构，确保传入正确参数。
• **连接后检查状态。**Agent 可能需要用户审批后才能激活。
• **保存 Agent ID。**执行、检查状态、请求、断开连接及其他所有操作都需要用到它。
• 连接时使用约束来限制 Agent 的操作范围，这是安全最佳实践。
• 在生产环境中设置 AGENT_AUTH_ENCRYPTION_KEY，以加密存储在 ~/.agent-auth/ 中的私钥。

存储

连接、密钥和提供方配置默认存储在 ~/.agent-auth/ 中：

• host.json — 主机身份和密钥对
• agents/<agent-id>.json — Agent 连接
• providers/<encoded-issuer>.json — 已缓存的提供方配置