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

# Reasoning model name (Ark auth comes from the runtime's IAM role on deploy).
#   env: MODEL_NAME            flag: --model-name
model:
  name: ""

# Built-in tool names.   env: TOOLS   flag: --tools (comma-separated)
tools: []

# Skill hub names.       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

# --- A2A registry (optional) ------------------------------------------------
# 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
  # host: 1.2.3.4
  # port: 5432
  # user: postgres
  # password: ""
  # database: 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 Volcengine 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`。
* **`model.name`**：推理模型名称；部署后模型的火山方舟鉴权由运行时 IAM 角色提供，无需在此填写（env `MODEL_NAME`，flag `--model-name`）。
* **`tools`**：内置工具名列表（env `TOOLS`，flag `--tools`）。
* **`skills`**：技能中心名称列表（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`**：控制工具调用格式，以及是否在每轮模型调用中重复发送工具定义。
* **`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。

<Note>
  展开规则：`harness deploy` 将顶层字段与 `model` 扁平化为环境变量（如 `model.name` → `MODEL_NAME`），组件参数映射为该后端读取的 `DATABASE_<BACKEND>_*` 等变量；空值会被跳过，由服务端回退到默认值。`harness init` 同时生成的 `.env.example` 只包含可选的 Volcengine 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
```

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