> ## Documentation Index
> Fetch the complete documentation index at: https://docs.veadk.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# 调用运行时

`invoke` 命令组用于向已部署的 Runtime 发送一次请求。默认从当前目录的 `agentkit.yaml` 读取 Runtime 端点、版本、鉴权和 A2A 配置；也可以通过 `--runtime-id` 或 `--endpoint` 直接指定目标。

<Note>
  `agentkit invoke "hello"` 会按兼容规则转换为 `agentkit invoke run "hello"`；文档中使用 `invoke run` 作为明确写法。`-ak` 也会转换为 `--apikey`，用于兼容 Python SDK 风格参数。
</Note>

调用前确认运行时已就绪，并准备目标所需的 API Key 或用户 token。`--runtime-id` 还需要管理凭证；已知端点并持有调用凭证时，可用 `--endpoint` 直接访问

<Warning>
  消息和请求体会发送到目标运行时及其模型、工具，可能产生用量费用。不要在测试请求中包含不应外发的数据；默认固定会话标识适合示例，独立会话应显式提供不同的 `session_id`
</Warning>

## invoke run

向 Runtime 发送消息或自定义 JSON payload。传入普通消息时，CLI 会发送 `{ "prompt": "<message>" }`；传入 `--payload` 时，会原样发送解析后的 JSON 对象。

每次请求默认带有 `user_id: agentkit_user` 与 `session_id: agentkit_sample_session` 上下文 headers。需要自定义用户或会话标识时，通过 `--headers` 传入同名字段覆盖默认值。

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `[message]` | 要发送的用户消息；不能与 `--payload` 同时使用。 | — |
| `--config-file <path>` | 读取指定生命周期配置文件；不能与 `--runtime-id` 或 `--endpoint` 同时使用。 | 当前目录的 `agentkit.yaml` |
| `-p, --payload <json>` | 要发送的 JSON payload；适合需要传递 `state_delta` 或 JSON-RPC 请求的场景。 | — |
| `-h, --headers <json>` | 要随请求发送的 JSON headers；所有值必须是字符串。 | — |
| `-r, --runtime-id <id>` | 直接调用指定 Runtime ID，并通过控制面解析端点与鉴权信息。 | — |
| `-e, --endpoint <url>` | 直接调用指定 Runtime endpoint。 | — |
| `--region <region>` | 解析 `--runtime-id` 时使用的区域。 | 自动感知 |
| `--a2a` | 在直接调用模式下强制使用 A2A JSON-RPC 传输。 | `false` |
| `--show-reasoning` | 流式输出时打印 LangChain `reasoning_content`。 | `false` |
| `--raw` | 输出原始流式事件或原始 JSON 响应；错误信息不带交互装饰。 | `false` |
| `--apikey <key>` | 显式指定 Bearer API Key；`--endpoint` 模式可用，不能与 `--runtime-id` 同时使用。 | — |

```bash lines theme={null}
# 读取当前目录的 agentkit.yaml
agentkit invoke run "你好，介绍一下你自己"

# 兼容简写，等价于上一条
agentkit invoke "你好，介绍一下你自己"
```

## 目标解析

未传 `--runtime-id` 或 `--endpoint` 时，CLI 读取 `agentkit.yaml`：

* `launch_type: local` 时调用本地 `http://127.0.0.1:<invoke_port>`；
* 云端部署会优先使用配置中保存的 `runtime_endpoint` 与鉴权信息；
* 如果配置只保存了 `runtime_id`，CLI 会用控制面查询当前版本端点与鉴权信息；
* `agent_type` 或 `template_type` 包含 `a2a` 时，CLI 自动使用 A2A 传输。

```bash lines theme={null}
agentkit invoke run "检查部署状态" --config-file ./agentkit.staging.yaml
```

传入 `--runtime-id` 时，CLI 会用管理凭据查询 Runtime 当前或指定版本。该模式会自动使用可解析的 `key_auth` 凭证；`custom_jwt` Runtime 必须通过 `--headers` 传入 OAuth token。

```bash lines theme={null}
agentkit invoke run "hello" \
  --runtime-id <runtime-id> \
  --headers '{"Authorization":"Bearer <oauth-token>","session_id":"session-1"}'
```

传入 `--endpoint` 时，CLI 不查询控制面，必须显式提供鉴权信息：

```bash lines theme={null}
agentkit invoke run \
  --payload '{"prompt":"hello","state_delta":{"locale":"zh"}}' \
  --endpoint https://runtime.example.com \
  --apikey <api-key>
```

## 传输与输出

CLI 会先尝试 `POST /invoke`。当该端点返回 `404` 或 `405` 时，会继续检测 ADK `/run_sse`；如果目标暴露 A2A AgentCard，也会使用 A2A JSON-RPC。显式传入 `--a2a` 或 `--payload` 中包含 `jsonrpc: "2.0"` 时，会直接使用 A2A JSON-RPC。

默认输出会从流式事件中提取答案文本；`--raw` 输出事件或响应原文，适合脚本解析。未传 `--raw` 时，如果模型输出 reasoning 内容，CLI 会显示提示；需要查看 reasoning 文本时传入 `--show-reasoning`。

```bash lines theme={null}
agentkit invoke run "请给出推理过程和答案" \
  --runtime-id <runtime-id> \
  --show-reasoning

agentkit invoke run --payload '{"jsonrpc":"2.0","method":"message/stream","params":{"message":{"role":"user","parts":[{"kind":"text","text":"hello"}]}},"id":1}' \
  --endpoint https://a2a.example.com \
  --headers '{"Authorization":"Bearer <token>"}' \
  --raw
```

## custom\_jwt 鉴权

`custom_jwt` Runtime 要求请求携带用户 OAuth token。对于 `--runtime-id` 或配置文件解析出的 Runtime，CLI 不会自动把登录会话中的 `id_token` 注入到通用 `invoke run` 请求中；请通过 `--headers` 显式传入 `Authorization`。

```bash lines theme={null}
agentkit login --identity-only <sso-address>

agentkit invoke run "hello" \
  --runtime-id <custom-jwt-runtime-id> \
  --headers '{"Authorization":"Bearer <oauth-token>"}'
```

身份仅登录会保存 OIDC 会话，不会生成 AgentKit 管理凭据。若还需要通过 `--runtime-id` 查询 Runtime，请另外配置 AK/SK，或使用普通 `agentkit login` 获取 STS 凭据。

## 常见检查

| 现象 | 检查方法 |
| - | - |
| 找不到运行时或列表为空 | 核对 `--provider`、`--region`、Runtime ID 与管理凭证所属账号 |
| 返回鉴权失败 | 检查目标的 `key_auth` 或 `custom_jwt`，以及 API Key 或 token 是否有效 |
| 请求成功但没有预期回答 | 使用 `--raw` 查看响应，并检查运行时日志和模型配置 |
| 帮助选项报错 | 使用 `agentkit invoke run --help`；此命令的 `-h` 表示 `--headers` |

`--show-reasoning` 只展示响应中实际返回的推理字段，不会要求模型生成或暴露额外信息