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

```bash lines theme={null}
agentkit harness init my-harness
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).
#
# `agentkit harness deploy` converts this file into the runtime's environment
# variables: top-level fields and `model` are flattened (model.name -> MODEL_NAME,
# tools -> TOOLS, ...); each component's `type` selects its backend, and the
# component's other params map to the env vars that backend reads (e.g. viking
# `project` -> DATABASE_VIKING_PROJECT). Empty values are skipped, so the server
# falls back to its own defaults.
#
# 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).
#   env: HARNESS_NAME          flag: --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.
#   env: MODEL_*               flag: --model-name
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.   env: TOOLS   flag: --tools (comma-separated)
tools: []

# Skill Hub slugs, ss-... spaces, or ss-...:s-... refs.
#   env: SKILLS  flag: --skills (comma-separated)
skills: []

# Agent instruction (empty = server default).
#   env: SYSTEM_PROMPT         flag: --system-prompt
system_prompt: ""

# Agent description, used by discovery and generated AgentCards.
#   env: DESCRIPTION           flag: --description
description: ""

# Agent runtime backend: adk (default) | codex.
#   env: RUNTIME               flag: --runtime
runtime: adk

# Per-run defaults. Both can be overridden by `agentkit harness invoke` flags.
#   env: MAX_LLM_CALLS         flag: --max-llm-calls
# 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` 将顶层字段与 `model` 扁平化为环境变量（如 `model.name` → `MODEL_NAME`），组件参数映射为该后端读取的 `DATABASE_<BACKEND>_*` 等变量；空值会被跳过，由服务端回退到默认值。`auth`、`cloud`、`capacity` 与 Sidecar 配置用于部署控制面，不作为普通用户配置传入智能体进程。`harness init` 同时生成的 `.env.example` 只包含可选的云厂商 AK/SK 占位符，智能体配置全部在 `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 端口 | 无 |
| `--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` |

```bash lines theme={null}
agentkit harness set --name my-harness --model-name doubao-pro --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` |

```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`） | 无 |

```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>` | 要发送的用户消息（必填）。 | — |
| `-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` |

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

agentkit harness invoke my-harness "总结本次会话" \
  --model-name doubao-pro \
  --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 只读保护已关闭。