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

# Harness

`harness` 命令组用于以无代码方式创建智能体：先初始化一个 `harness.yaml`，再逐项设置字段，最后直接部署为运行时，无需编写任何应用代码。

## harness init

创建一个 harness 目录，包含 `harness.yaml` 与 `.env.example`，用于Harness。

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `[name]` | harness 名称（传 `.` 表示当前目录） | 无 |
| `-r, --region <region>` | 部署区域。 | 所选云厂商的默认区域 |
| `-y, --yes` | 跳过交互提示并使用默认值 | `false` |
| `-f, --force` | 在非空目录中脚手架 / 覆盖已有 `harness.yaml` | `false` |
| `--mcp-server <json>` | 远程 MCP 服务 JSON，可重复；单独传 `[]` 清空列表 | 不覆盖 |

```bash lines theme={null}
# Volcengine
agentkit harness init my-harness

# BytePlus: choose this command instead
agentkit --provider byteplus harness init my-harness --region ap-southeast-1
```

`harness.yaml` 是无代码智能体的唯一配置来源，`harness deploy` 会将其展开为运行时的环境变量。生成的文件里，常用字段处于启用状态，各组件的可选参数以注释形式按后端分组给出——设好组件的 `type` 后，取消注释该后端下的参数即可。完整内容如下：

```yaml title="harness.yaml" lines theme={null}
# =============================================================================
# AgentKit harness configuration (code-free agent).
#
# Configure with `agentkit harness set ...` or by editing this file. For a
# component, uncomment the params under the backend you set as `type`.
# =============================================================================

# Harness / runtime name (also the knowledgebase & long-term-memory index name).
harness_name: "my-harness"

# Deployment cloud selected by `agentkit harness init`.
cloud:
  provider: volcengine
  region: cn-beijing
  # A horizontally scaled OAuth Harness should use a private connection to its
  # shared session database. Keep public network enabled for authenticated APIG
  # ingress, and use a dedicated least-privilege security group.
  # network:
  #   enable_public_network: true
  #   enable_private_network: true
  #   vpc_id: ${HARNESS_RUNTIME_VPC_ID}
  #   subnet_ids: [${HARNESS_RUNTIME_SUBNET_ID}]
  #   security_group_ids: [${HARNESS_RUNTIME_SECURITY_GROUP_ID}]
  #   enable_shared_internet_access: true

# Reasoning model. Direct mode preserves the legacy Runtime-IAM key lookup.
# For a shared OAuth Harness, obo_broker sends a short-lived user+Runtime TIP to
# a fixed APIG model egress; the gateway/Broker replaces it with the hosted
# downstream credential, so the real provider key never enters this process.
model:
  name: ""
  # provider: openai
  # api_base: https://<model-egress-apig>/v1
  # credential_mode: obo_broker
  # target_alias: model
  # target_audience: trn:agentkit:model-gateway
  # workload_discovery_url: https://<workload-issuer>/.well-known/openid-configuration
  # workload_issuer: https://<workload-issuer>
  # workload_pool: default
  # identity_region: cn-beijing

# Runtime and model-call admission capacity. In OAuth mode, max_instance > 1
# requires a shared MySQL/PostgreSQL short-term-memory backend; local/sqlite
# sessions cannot safely span replicas. The model limits are per Runtime
# instance; enforce tenant-wide TPM/TPD again at Model Gateway.
capacity:
  # cpu_milli: 4000
  # memory_mb: 8192
  # min_instance: 4
  # max_instance: 10
  # max_concurrency: 32
  # model_max_inflight: 12
  # model_max_inflight_per_user: 1
  # model_queue_timeout_seconds: 45
  # model_request_timeout_seconds: 120
  # model_max_output_tokens: 1024
  # session_db_pool_size: 5
  # session_db_max_overflow: 3
  # session_db_pool_timeout_seconds: 10
  # session_db_pool_recycle_seconds: 300

# Built-in tool names; configure with --tools (comma-separated)
tools: []
mcp_servers: []

# Skill Hub slugs, ss-... spaces, or ss-...:s-... refs.
skills: []

# Agent instruction (empty = server default).
system_prompt: ""

# Agent description, used by discovery and generated AgentCards.
description: ""

# Agent runtime backend: adk (default) | codex.
runtime: adk

# Per-run defaults. Both can be overridden by `agentkit harness invoke` flags.
# max_llm_calls: 20

# Tool-call behavior.
# structured_tool_calls: false
# include_tools_every_turn: true

# Managed Harness Sidecar optimizations (optional). SQL readonly protection is
# server-owned and is enabled automatically with mcp_resilience.
# sidecar:
#   enabled: true
#   profile: default
#   component_overrides:
#     context_engine: true
#     compressor: false
#     verifier: false
#     long_run_control: false
#     mcp_resilience: false

# --- A2A registry (optional) ------------------------------------------------
# Configure with --registry / --registry-space-id / --registry-space-name.
# registry:
#   type: agentkit_a2a
#   space_id: ""
#   top_k: 3
#   endpoint: https://open.volcengineapi.com/
#   region: cn-beijing

# --- Knowledge base ----------------------------------------------------------
#   type -> env: KNOWLEDGEBASE_TYPE   flag: --knowledgebase-type
#   "" disables it. Supported: viking | opensearch | redis
knowledgebase:
  type: ""
  # -- viking --      flags: --knowledgebase-project / --knowledgebase-region
  # project: my-project
  # region: cn-beijing
  # -- opensearch --  flags: --knowledgebase-host / -port / -username / -password / -use-ssl
  # host: 1.2.3.4
  # port: 9200
  # username: admin
  # password: ""
  # use_ssl: true
  # -- redis --       flags: --knowledgebase-host / -port / -username / -password / -db
  # host: 1.2.3.4
  # port: 6379
  # username: default
  # password: ""
  # db: 0

# --- Long-term memory --------------------------------------------------------
#   type -> env: LONG_TERM_MEMORY_TYPE   flag: --long-term-memory-type
#   "" disables it. Supported: viking | opensearch | redis | mem0
long_term_memory:
  type: ""
  # -- viking --      flags: --long-term-memory-project / --long-term-memory-region
  # project: my-project
  # region: cn-beijing
  # -- opensearch --  flags: --long-term-memory-host / -port / -username / -password
  # host: 1.2.3.4
  # port: 9200
  # username: admin
  # password: ""
  # -- redis --       flags: --long-term-memory-host / -port / -password / -db
  # host: 1.2.3.4
  # port: 6379
  # password: ""
  # db: 0
  # -- mem0 --        flags: --long-term-memory-api-key / -api-key-id / -project-id / -base-url
  # api_key: ""
  # api_key_id: ""
  # project_id: ""
  # base_url: https://api.mem0.ai/v1

# --- Short-term memory (session store) ---------------------------------------
#   type -> env: SHORT_TERM_MEMORY_TYPE   flag: --short-term-memory-type
#   local (default) | sqlite | mysql | postgresql
short_term_memory:
  type: local
  # -- mysql --       flags: --short-term-memory-host / -user / -password / -database / -charset
  # host: 1.2.3.4
  # user: root
  # password: ""
  # database: harness
  # charset: utf8
  # -- postgresql --  flags: --short-term-memory-host / -port / -user / -password / -database / -schema
  # host: 1.2.3.4
  # port: 5432
  # user: postgres
  # password: ""
  # database: harness
  # schema: pdsa_shared_harness

# --- Authentication (optional) -----------------------------------------------
# Omit this block to deploy with the default API-key auth (key_auth). Add it to
# gate the runtime with OAuth2/JWT (custom_jwt): the API gateway then only accepts
# tokens issued by `discovery_url`'s user pool whose audience is one of
# `allowed_ids`. Set up the user pool / client in the selected cloud's Identity console.
#   flags: --discovery-url / --allowed-id
# auth:
#   discovery_url: "https://userpool-<id>.userpool.auth.id.cn-beijing.volces.com/.well-known/openid-configuration"
#   allowed_ids: ["<client-id>"]
```

字段说明：

* **`harness_name`**：harness 与运行时名称，同时用作知识库、长期记忆的索引名（env `HARNESS_NAME`，flag `--name`）。
* **`cloud`**：部署使用的云厂商和区域，由 `harness init` 写入；云厂商为 `volcengine` 或 `byteplus`。
* **`cloud.network`（可选）**：运行时网络配置。`enable_public_network` 控制公网入口，`enable_private_network` 启用私有 VPC，`vpc_id`、`subnet_ids` 与 `security_group_ids` 指定私有网络资源，`enable_shared_internet_access` 控制私有网络共享公网出口。启用私有网络时必须提供 VPC 与子网。
* **`model.name`**：推理模型名称（env `MODEL_NAME`，flag `--model-name`）。
* **`model.credential_mode`（可选）**：设为 `obo_broker` 时启用共享 OAuth Harness 的托管模型出口。该模式要求同时配置 `auth`，并提供 `model.provider`、`model.api_base`、`model.target_alias`、`model.target_audience`、`model.workload_discovery_url` 与 `model.workload_issuer`；不要在该模式下写入模型 API Key。
* **`capacity`（可选）**：运行时资源、并发和模型请求准入配置。可设置 `cpu_milli`、`memory_mb`、`min_instance`、`max_instance`、`max_concurrency`、`model_max_inflight`、`model_max_inflight_per_user`、`model_queue_timeout_seconds`、`model_request_timeout_seconds`、`model_max_output_tokens`、`session_db_pool_size`、`session_db_max_overflow`、`session_db_pool_timeout_seconds` 与 `session_db_pool_recycle_seconds`。
* **`tools`**：内置工具名列表（env `TOOLS`，flag `--tools`）。
* **`skills`**：Skill Hub slug、空间或 `space:skill` 引用列表（env `SKILLS`，flag `--skills`）。
* **`system_prompt`**：智能体指令，留空则使用服务端默认（env `SYSTEM_PROMPT`，flag `--system-prompt`）。
* **`description`**：用于发现和生成 AgentCard 的智能体描述（env `DESCRIPTION`，flag `--description`）。
* **`runtime`**：智能体运行时后端，`adk`（默认）或 `codex`（env `RUNTIME`，flag `--runtime`）。
* **`max_llm_calls`**：每次运行允许的默认最大 LLM 调用次数；`agentkit harness invoke --max-llm-calls` 可为单次请求覆盖。
* **`structured_tool_calls`** / **`include_tools_every_turn`**：控制工具调用格式，以及是否在每轮模型调用中重复发送工具定义。
* **`sidecar`（可选）**：托管 Harness Sidecar 配置。`profile` 选择组件 profile，`component_overrides` 控制 `context_engine`、`compressor`、`verifier`、`long_run_control` 与 `mcp_resilience` 等组件。
* **`registry`**：可选 A2A registry。`space_id` 选择空间，`top_k` 控制最多检索的 AgentCard 数量，`endpoint` 与 `region` 指定服务位置。
* **`knowledgebase`**：知识库。`type` 留空即禁用，支持 `viking`、`opensearch`、`redis`；设好 `type` 后取消注释该后端下对应的连接参数。
* **`long_term_memory`**：长期记忆。`type` 留空即禁用，支持 `viking`、`opensearch`、`redis`、`mem0`。
* **`short_term_memory`**：短期会话存储。`type` 为 `local`（默认）、`sqlite`、`mysql` 或 `postgresql`。
* **`auth`（可选）**：省略则使用默认的 API Key 鉴权 `key_auth`；填入 `discovery_url` 与 `allowed_ids` 则改用 OAuth2/JWT `custom_jwt`，网关仅接受该用户池签发、受众在白名单内的 token。

下列字段需要直接编辑 `harness.yaml`，当前不由 `harness set` 生成。

| 字段 | 类型 | 默认值 | 说明 |
| - | - | - | - |
| `cloud.network.enable_public_network` | boolean | `true` | 是否保留 Runtime 公网入口。 |
| `cloud.network.enable_private_network` | boolean | `false` | 是否启用私有 VPC 网络。 |
| `cloud.network.vpc_id` | string | — | 私有网络使用的 VPC ID；启用私有网络时必填。 |
| `cloud.network.subnet_ids` | string\[] | — | 私有网络使用的子网 ID，最多 5 个；启用私有网络时必填。 |
| `cloud.network.security_group_ids` | string\[] | — | 私有网络使用的安全组 ID，最多 5 个。 |
| `cloud.network.enable_shared_internet_access` | boolean | `false` | 私有网络下是否启用共享公网出口。 |
| `model.provider` | string | — | 托管模型出口的模型提供方标识。 |
| `model.api_base` | string | — | 托管模型出口的 HTTPS API Base URL。 |
| `model.credential_mode` | `obo_broker` | — | 启用代表用户的托管模型凭据代理；必须同时配置 `auth`。 |
| `model.target_alias` | string | — | 模型出口的固定小写别名。 |
| `model.target_audience` | string | — | 模型出口校验的目标受众。 |
| `model.workload_discovery_url` | string | — | 工作负载身份的 OIDC discovery URL，必须属于 `model.workload_issuer`。 |
| `model.workload_issuer` | string | — | 工作负载身份 issuer。 |
| `model.workload_pool` | string | `default` | 工作负载身份池。 |
| `model.identity_region` | string | 部署区域 | 工作负载身份区域。 |
| `capacity.cpu_milli` | integer | 平台默认 | Runtime CPU，范围为 `250` 到 `32000`。 |
| `capacity.memory_mb` | integer | 平台默认 | Runtime 内存，范围为 `512` 到 `131072`。 |
| `capacity.min_instance` | integer | OAuth 或 Sidecar 启用时为 `1` | Runtime 最小实例数，范围为 `1` 到 `100`。 |
| `capacity.max_instance` | integer | OAuth 或 Sidecar 启用时为 `1` | Runtime 最大实例数，范围为 `1` 到 `100`。 |
| `capacity.max_concurrency` | integer | 平台默认 | Runtime 单实例并发上限，范围为 `1` 到 `1000`。 |
| `capacity.model_max_inflight` | integer | — | 单个 Runtime 实例允许的模型并发请求上限，范围为 `1` 到 `1000`。 |
| `capacity.model_max_inflight_per_user` | integer | — | 单用户模型并发请求上限，范围为 `1` 到 `100`；不能超过 `model_max_inflight`。 |
| `capacity.model_queue_timeout_seconds` | integer | — | 模型请求排队超时秒数，范围为 `1` 到 `600`。 |
| `capacity.model_request_timeout_seconds` | integer | — | 模型请求执行超时秒数，范围为 `1` 到 `900`。 |
| `capacity.model_max_output_tokens` | integer | — | 单次模型响应 token 上限，范围为 `128` 到 `16384`。 |
| `capacity.session_db_pool_size` | integer | — | 每个 Runtime 副本的共享会话数据库连接池大小，范围为 `1` 到 `100`。 |
| `capacity.session_db_max_overflow` | integer | — | 每个 Runtime 副本可额外打开的共享会话数据库连接数，范围为 `0` 到 `100`。 |
| `capacity.session_db_pool_timeout_seconds` | integer | — | 获取共享会话数据库连接的等待秒数，范围为 `1` 到 `120`。 |
| `capacity.session_db_pool_recycle_seconds` | integer | — | 共享会话数据库连接回收秒数，范围为 `30` 到 `3600`。 |

<Note>
  `harness deploy` 与 `harness dev` 会读取项目 `.env` 并解析 `harness.yaml` 中的 `${VAR}`，已有 shell 环境变量优先。数据库密码等敏感值应使用变量引用，并将 `.env` 排除出版本控制。`.env.example` 只包含可选的云凭据占位符；模型、组件、网络和容量在 `harness.yaml` 中配置
</Note>

## harness set

设置 `harness.yaml` 中的字段（局部更新，仅修改传入的字段）。不带任何标志运行时会列出当前字段。字段分为若干组：核心（模型 / 工具 / 技能 / 提示词 / 运行时）、knowledgebase、long-term-memory、short-term-memory 以及鉴权。设置某个组件时，请先设置其 `--<组件>-type`，再设置连接参数。

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `--name <name>` | harness/运行时名称 | 无 |
| `--model-name <name>` | 推理模型名称 | 无 |
| `--tools <list>` | 逗号分隔的内置工具 | 无 |
| `--skills <list>` | 逗号分隔的技能中心名称 | 无 |
| `--system-prompt <text>` | 智能体指令 | 无 |
| `--description <text>` | 用于发现和 AgentCard 的智能体描述。 | 无 |
| `--runtime <backend>` | 智能体运行时后端：`adk` \| `codex` | 无 |
| `--max-llm-calls <n>` | 每次运行默认允许的最大 LLM 调用次数，必须为正整数。 | 无 |
| `--knowledgebase-type <type>` | knowledgebase 后端类型（传 `""` 可禁用） | 无 |
| `--knowledgebase-project <value>` | knowledgebase 项目 | 无 |
| `--knowledgebase-region <value>` | knowledgebase 区域 | 无 |
| `--knowledgebase-host <value>` | knowledgebase 主机 | 无 |
| `--knowledgebase-port <value>` | knowledgebase 端口 | 无 |
| `--knowledgebase-username <value>` | knowledgebase 用户名 | 无 |
| `--knowledgebase-password <value>` | knowledgebase 密码 | 无 |
| `--knowledgebase-use-ssl` | knowledgebase 启用 use\_ssl | `false` |
| `--knowledgebase-cert-path <value>` | knowledgebase cert\_path | 无 |
| `--knowledgebase-secret-token <value>` | knowledgebase secret\_token | 无 |
| `--knowledgebase-db <value>` | knowledgebase db | 无 |
| `--long-term-memory-type <type>` | long\_term\_memory 后端类型（传 `""` 可禁用） | 无 |
| `--long-term-memory-project <value>` | long\_term\_memory 项目 | 无 |
| `--long-term-memory-region <value>` | long\_term\_memory 区域 | 无 |
| `--long-term-memory-host <value>` | long\_term\_memory 主机 | 无 |
| `--long-term-memory-port <value>` | long\_term\_memory 端口 | 无 |
| `--long-term-memory-username <value>` | long\_term\_memory 用户名 | 无 |
| `--long-term-memory-password <value>` | long\_term\_memory 密码 | 无 |
| `--long-term-memory-use-ssl` | long\_term\_memory 启用 use\_ssl | `false` |
| `--long-term-memory-cert-path <value>` | long\_term\_memory cert\_path | 无 |
| `--long-term-memory-secret-token <value>` | long\_term\_memory secret\_token | 无 |
| `--long-term-memory-db <value>` | long\_term\_memory db | 无 |
| `--long-term-memory-api-key <value>` | long\_term\_memory api\_key | 无 |
| `--long-term-memory-api-key-id <value>` | long\_term\_memory api\_key\_id | 无 |
| `--long-term-memory-project-id <value>` | long\_term\_memory project\_id | 无 |
| `--long-term-memory-base-url <value>` | long\_term\_memory base\_url | 无 |
| `--short-term-memory-type <type>` | short\_term\_memory 后端类型（传 `""` 可禁用） | 无 |
| `--short-term-memory-host <value>` | short\_term\_memory 主机 | 无 |
| `--short-term-memory-user <value>` | short\_term\_memory 用户 | 无 |
| `--short-term-memory-password <value>` | short\_term\_memory 密码 | 无 |
| `--short-term-memory-database <value>` | short\_term\_memory 数据库 | 无 |
| `--short-term-memory-charset <value>` | short\_term\_memory 字符集 | 无 |
| `--short-term-memory-port <value>` | short\_term\_memory 端口 | 无 |
| `--short-term-memory-schema <value>` | PostgreSQL schema 名称 | 无 |
| `--discovery-url <url>` | OAuth2/JWT OIDC discovery URL（启用 custom\_jwt） | 无 |
| `--allowed-id <ids>` | 逗号分隔的允许客户端 ID | 无 |
| `--structured-tool-calls` | 使用结构化工具调用。 | 当前配置值 |
| `--no-structured-tool-calls` | 禁用结构化工具调用。 | 当前配置值 |
| `--include-tools-every-turn` | 在每轮模型调用中发送工具定义。 | 当前配置值 |
| `--reuse-tool-context` | 复用工具上下文，不在每轮重复发送工具定义。 | 当前配置值 |
| `--registry <uri>` | A2A registry：`default`、`disabled`、`agentkit://...` 或 HTTP(S) URL。 | 无 |
| `--registry-space-id <id>` | AgentKit A2A 空间 ID。 | 无 |
| `--registry-space-name <name>` | AgentKit A2A 空间名称；必须唯一。 | 无 |
| `--registry-top-k <n>` | 最多检索的 AgentCard 数量，必须为正整数。 | 无 |
| `--registry-endpoint <url>` | AgentKit A2A registry 端点。 | 当前云环境的 AgentKit 端点 |
| `--registry-region <region>` | AgentKit A2A registry 区域。 | `cloud.region` |
| `--mcp-server <json>` | 远程 MCP 服务 JSON，可重复；单独传 `[]` 清空列表 | 不覆盖 |

```bash lines theme={null}
agentkit harness set --name my-harness --model-name "your-model-name" --runtime adk

agentkit harness set --registry default --registry-space-name Default --registry-top-k 3
```

<Tip>
  只有显式传入的标志会被修改。若要配置某个组件，请先设置它的 `--<组件>-type`，再补充其连接参数。
</Tip>

## harness dev

根据当前目录的 `harness.yaml` 在本地启动 Harness 服务，用于开发和调试。默认监听本机的 `127.0.0.1:8000`；如需从其它设备访问，可显式修改监听地址。

| 标志 | 说明 | 默认值 |
| - | - | - |
| `-p, --port <port>` | 服务监听端口。 | `8000` |
| `--host <host>` | 服务监听地址。 | `127.0.0.1` |
| `--reload` | 服务代码变化时自动重启。 | `false` |
| `--python <bin>` | 启动服务使用的 Python 解释器。 | `python3` |

先准备 Python 3 与 Harness 服务依赖。命令启动时会输出依赖清单路径；缺少模块时，使用同一个 `--python` 解释器安装该清单后重试。此命令不会自动创建 Python 环境或安装依赖；修改 `harness.yaml` 后需重新启动，`--reload` 只监视服务代码

本地监听不代表离线运行：调用模型、MCP、知识库或远程数据库仍需要相应凭据与网络，并可能产生费用

```bash lines theme={null}
agentkit harness dev --reload --port 8000
```

## harness deploy

构建 harness 镜像，并根据 `harness.yaml` 创建或更新运行时。

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `-r, --region <region>` | 运行时部署区域 | 无 |
| `-p, --project <name>` | AgentKit 项目 | `default` |
| `--discovery-url <url>` | OIDC discovery URL（启用 OAuth2/JWT，覆盖 `harness.yaml`） | 无 |
| `--allowed-id <ids>` | 逗号分隔的允许客户端 ID（覆盖 `harness.yaml`） | 无 |
| `--cronjob` | 启用持久化定时任务 | `false` |
| `--cronjob-tos-bucket <bucket>` | 保存任务、状态和结果的已有 TOS 桶名 | `cronjob.tos_bucket` |
| `--cronjob-tos-region <region>` | TOS 桶所在区域 | 运行时区域 |

<Warning>
  部署需要所选云厂商的控制面凭据，将构建镜像并创建或更新云端 Runtime，可能产生费用并改变线上行为。先确认模型可用、组件连接配置完整，以及地域和项目正确。模型名示例中的 `your-model-name` 必须替换为账号可调用的模型或端点 ID
</Warning>

```bash lines theme={null}
agentkit harness deploy --project default --region cn-beijing
```

配置 `auth` 后，部署会创建 `custom_jwt` Runtime。部署完成后，将返回的 Runtime ID 与 HTTPS endpoint 发布到租户登录发现文档的 `shared_harnesses` 中，用户即可通过 [`agentkit chat <alias>`](/productions/agentkit-cli/preview/zh/commands/chat) 使用共享聊天。

```json lines theme={null}
{
  "shared_harnesses": {
    "harness": {
      "runtime_id": "r-1234567890abcdef",
      "endpoint": "https://runtime.example.com"
    }
  }
}
```

## harness invoke

调用已部署的 Harness，并可为本次请求临时覆盖模型、系统提示词、工具、技能、运行时后端或 A2A registry。覆盖项只影响当前请求，不会修改 `harness.yaml`。

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `<name>` | Harness 或 Runtime 名称（必填）。 | — |
| `[message]` | 用户消息；省略时读取调用配置的 `message` 或 `prompt` | — |
| `-r, --region <region>` | 云区域。 | 自动感知 |
| `--rev <n>` | 要调用的 Runtime 版本。 | 当前版本 |
| `--user-id <id>` | 本次运行的 `user_id`。 | `agentkit_user` |
| `--session-id <id>` | 本次运行的 `session_id`；未设置时自动生成。 | 自动生成 |
| `--token <jwt>` | `custom_jwt` Harness 使用的 Bearer token。 | — |
| `--tip-token-key <key>` | 转发到 Harness 请求上下文的 TIP token key。 | — |
| `--apikey <key>` | 显式指定 Bearer API Key。 | — |
| `--raw` | 输出原始 Harness 响应或流式事件。 | `false` |
| `--model-name <name>` | 本次请求使用的模型名称。 | 配置值 |
| `--system-prompt <text>` | 本次请求使用的系统提示词。 | 配置值 |
| `--tools <list>` | 本次请求使用的工具列表，多个值用逗号分隔。 | 配置值 |
| `--skills <list>` | 本次请求使用的 Skill Hub slug、空间或 `space:skill` 引用。 | 配置值 |
| `--runtime <backend>` | 本次请求使用的运行时后端：`adk` 或 `codex`。 | 配置值 |
| `--max-llm-calls <n>` | 本次请求允许的最大 LLM 调用次数，必须为正整数。 | 配置值 |
| `--registry <uri>` | 本次请求使用的 A2A registry：`default`、`agentkit://...` 或 HTTP(S) URL。 | 配置值 |
| `--registry-space-id <id>` | A2A registry 空间 ID。 | 配置值 |
| `--registry-space-name <name>` | A2A registry 空间名称。 | 配置值 |
| `--registry-top-k <n>` | A2A AgentCard 检索数量，必须为正整数。 | 配置值 |
| `--registry-endpoint <url>` | A2A registry 端点。 | 配置值 |
| `--registry-region <region>` | A2A registry 区域。 | Runtime 区域 |
| `--protocol <protocol>` | 传输协议：`invoke` 或 `run_sse`。 | `run_sse` |
| `--mcp-server <json>` | 远程 MCP 服务 JSON，可重复；单独传 `[]` 清空列表 | 不覆盖 |
| `-c, --config <path>` | 读取本次调用的 YAML 或 JSON 配置 | — |
| `--harness-merge` | 要求目标运行时合并覆盖项与其默认 Harness 配置 | 不发送，使用服务端行为 |
| `--harness-enhance <json>` | 传入一次性 `harness_enhance` JSON 对象，需目标运行时支持 | — |

```bash lines theme={null}
agentkit harness invoke my-harness "你好，介绍一下你自己"

agentkit harness invoke my-harness "总结本次会话" \
  --model-name "your-model-name" \
  --max-llm-calls 10 \
  --registry default
```

对于使用 `custom_jwt` 鉴权的 Harness，可以通过 `--token` 显式传入 Bearer token，也可以先运行 `agentkit login --identity-only <sso-address>` 保存 OIDC 会话。CLI 只会在 Runtime endpoint 为 HTTPS、Runtime 的 discovery URL 与当前登录 issuer 匹配且当前 OAuth client ID 位于允许列表时自动转发缓存的 `id_token`。

## harness sidecar catalog

输出 Harness Sidecar Product Component Catalog。该命令只打印 JSON，不创建或修改云资源；可用于在 Studio、CI 或脚本中展示当前 profile 下的可选组件、可用状态和默认选择。

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `--profile <profile>` | Product Component profile：`default` 或 `ops`。 | `ops` |

```bash lines theme={null}
agentkit harness sidecar catalog --profile ops
```

输出包含 `schema_version`、`catalog_version`、`profiles`、`selected_profile`、`components`、`total_component_count` 与 `selectable_component_count`。其中 `components[].selected_by_profile` 表示该组件是否由当前 profile 默认选中，`components[].availability.available` 表示当前 Runtime 合约是否可用。

## harness sidecar resolve

将 profile 与组件开关解析为确定性的 Harness Sidecar plan。该命令只输出 JSON 计划；当计划无效时会返回非零退出码，便于发布前校验 `harness_sidecar.component_overrides` 是否可用。

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `--profile <profile>` | Product Component profile：`default` 或 `ops`。 | `ops` |
| `--disabled` | 关闭 Sidecar 选择，输出空的有效组件列表。 | `false` |
| `--component <id=true\|false>` | 覆盖一个可选组件；可重复传入。支持 `context_engine`、`compressor`、`verifier`、`long_run_control` 与 `mcp_resilience`。 | — |
| `--catalog-version <version>` | 期望的 Catalog 版本。 | `2026.07.1` |
| `--runtime-version <version>` | 目标托管 Runtime 版本；未指定时由平台选择。 | — |

```bash lines theme={null}
agentkit harness sidecar resolve \
  --profile default \
  --component context_engine=true \
  --component mcp_resilience=true
```

输出中的 `effective_components` 是最终启用组件；`activation_targets` 描述运行时组件、模型代理和 MCP 网关是否会被启用；`warnings` 列出有效但需要关注的选择结果；`plan_hash` 用于发布后核验运行时实际加载的计划。`mcp_resilience` 会自动带上 SQL 只读保护，`sql_readonly` 不能作为 `--component` 直接选择。使用 `ops` profile 但关闭 `mcp_resilience` 时，计划会提示 SQL 只读保护已关闭。

## 远程 MCP 服务

在 `harness.yaml` 中配置 `mcp_servers`，即可与内置工具同时使用远程 MCP 服务。`harness init` 和 `harness set` 保存配置，`harness dev`、`harness deploy` 加载配置，`harness invoke` 可仅覆盖本次调用

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `mcp_servers` | 服务列表；空列表禁用远程 MCP | `[]` |
| `protocol` | `streamable-http` 或 `sse` | `streamable-http` |
| `endpoint` | 必填的 HTTP(S) 地址，不接受 URL 用户信息或片段 | — |
| `api_key` | 可选凭据，以 `Authorization: Bearer` 发送；支持环境变量占位符 | — |

```yaml title="harness.yaml" lines theme={null}
mcp_servers:
  - protocol: streamable-http
    endpoint: https://mcp.example.com/mcp
    api_key: ${MCP_API_KEY}
```

```bash lines theme={null}
agentkit harness set --mcp-server '{"endpoint":"https://mcp.example.com/mcp","api_key":"${MCP_API_KEY}"}'
agentkit harness invoke my-harness "List available reports" --mcp-server '{"endpoint":"https://mcp.example.com/mcp","api_key":"${MCP_API_KEY}"}'
agentkit harness invoke my-harness "Answer without remote tools" --mcp-server '[]'
```

在当前项目的 `.env` 中设置 `MCP_API_KEY`，并将 `.env` 排除在版本控制之外。`init` 和 `set` 保留占位符；部署、运行或调用时解析实际值。命令行 MCP 列表整体替换调用配置中的列表，`[]` 不能与其他 `--mcp-server` 同时使用。请求未指定 MCP 时沿用部署配置；显式空列表只清除远程 MCP，不清除内置工具

共享 OAuth Harness 只接受 `mcp_servers` 作为 Harness 覆盖项；其他覆盖字段会被拒绝

## 调用配置文件

使用 `--config` 保存可复用的调用设置。命令行参数优先于调用文件，文件中的字段再作为本次请求发送；未指定的智能体字段沿用目标运行时支持的默认行为。配置文件不会修改 `harness.yaml` 或重新部署运行时

```yaml title="invoke.yaml" lines theme={null}
message: Summarize the latest operational report
protocol: run_sse
user_id: report-reader
max_llm_calls: 8
harness:
  system_prompt: Produce a concise report with sources
  tools: [web_search]
  mcp_servers:
    - endpoint: https://mcp.example.com/mcp
      api_key: ${MCP_API_KEY}
```

```bash lines theme={null}
agentkit harness invoke my-harness --config invoke.yaml
agentkit harness invoke my-harness "Focus on unresolved issues" --config invoke.yaml --max-llm-calls 4
```

| 标志/参数 | 说明 | 默认值 |
| - | - | - |
| `message` / `prompt` | 消息字符串 | 必须在文件或位置参数中提供 |
| `region`, `rev` | 目标区域和运行时版本 | 自动解析、当前版本 |
| `user_id`, `session_id` | 本次运行的用户和会话 ID | `agentkit_user`；随机会话 |
| `token`, `tip_token_key`, `apikey` / `api_key` | 显式调用凭据 | — |
| `raw` | 是否输出原始响应 | `false` |
| `protocol` | `invoke` 或 `run_sse` | `run_sse` |
| `max_llm_calls` | 本次运行的最大模型调用次数，正整数 | 目标运行时默认值 |
| `harness` / `overrides` | 本次智能体覆盖对象 | — |
| `harness.model_name`, `harness.system_prompt`, `harness.runtime` | 模型、系统提示词、运行后端 | 不覆盖 |
| `harness.tools`, `harness.skills` | 逗号分隔字符串或字符串数组 | 不覆盖 |
| `harness.mcp_servers` | 本次使用的远程 MCP 列表 | 不覆盖 |
| `registry`, `registry_space_id`, `registry_space_name`, `registry_top_k`, `registry_endpoint`, `registry_region` | A2A 注册表与检索参数；`registry_top_k` 为正整数 | 不覆盖 |
| `harness_merge` | 布尔值，传给支持合并默认配置的目标运行时 | 不发送 |
| `harness_enhance` | 增强配置对象，`components` 支持字符串数组或逗号分隔字符串，具体字段需目标运行时支持 | 不发送 |

`harness` 中的模型、工具、技能、系统提示词和运行后端也可写在顶层；同名顶层字段覆盖嵌套字段，`model.name` 可作为模型名称来源。除 MCP 凭据占位符外，不应假定任意调用字段会展开环境变量；凭据优先使用登录会话或命令支持的默认凭据来源

## 定时任务

启用 `cronjob` 后，可通过 `harness cronjob` 创建周期或一次性调用，查看结果，并暂停、恢复或取消执行。完整配置、参数与限制见 [Harness 定时任务](/productions/agentkit-cli/preview/zh/commands/harness-cronjob)

## 验证与会话存储

部署后运行 `agentkit runtime show my-harness` 确认当前版本，再用 `agentkit harness invoke my-harness "你好"` 验证模型响应。Runtime 就绪不能保证模型凭据、MCP 或数据库均可用；调用失败时查看 `agentkit runtime logs my-harness --limit 200`

本地内存会话随进程结束而丢失，SQLite 会话依赖单个实例的文件。共享 OAuth Harness 扩容到多个实例前，应配置 MySQL 或 PostgreSQL 短期记忆和可达的私有网络。托管 Sidecar 的地区、容量和鉴权限制见 [Harness Sidecar](/productions/agentkit-cli/preview/zh/agentkit-yaml#harness-sidecar)