> ## 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 名称（传 `.` 表示当前目录） | 无 |
| `-y, --yes` | 跳过交互提示并使用默认值 | `false` |
| `-f, --force` | 在非空目录中脚手架 / 覆盖已有 `harness.yaml` | `false` |

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

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

# 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 runtime backend: adk (default) | codex.
#   env: RUNTIME               flag: --runtime
runtime: adk

# --- 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`）。
* **`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`）。
* **`runtime`**：智能体运行时后端，`adk`（默认）或 `codex`（env `RUNTIME`，flag `--runtime`）。
* **`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>` | 智能体指令 | 无 |
| `--runtime <backend>` | 智能体运行时后端：`adk` \| `codex` | 无 |
| `--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 | 无 |

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

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