Harness Beta

Harness 是 AgentKit 提供的「动态装配、调用时按需覆写」的 Agent 工作流。一个 Harness 在创建时声明一套默认装配（模型、系统提示词、工具、技能、运行时、知识库与记忆等），部署为云端运行时后即可按名调用；在单次调用时还能临时覆写部分参数，不改变已部署的默认配置，便于在一次部署内对比 N 种模型 / 提示词 / 工具 / 技能组合。

完整生命周期由以下命令串起：

plaintext

agentkit init <name> --template harness     # 1. 生成 harness 项目骨架
agentkit add harness --name <name> ...      # 2. 生成 / 更新 <name>.harness.json 配置
agentkit deploy --harness <name> ...        # 3. 云端构建 + 部署为运行时，回写 harness.json 注册表
agentkit invoke harness <name> "<prompt>"   # 4. 按名调用（支持一次性覆写、流式）
agentkit list harness                       # 5. 列出已部署的 harness 运行时

部署出的运行时同时对外暴露三类接口：

POST /harness/invoke —— Harness 专属入口，支持一次性覆写；
ADK Web/API 路由（/run_sse、/list-apps、会话管理等）；
A2A 协议路由（/.well-known/agent-card.json 及 JSON-RPC）。

1. init —— 生成 Harness 项目骨架

agentkit init <name> --template harness 在 --directory（默认当前目录）下创建一个 Harness 项目目录，内含部署所需的 .env.example 与 Dockerfile（镜像从 VeADK 主分支构建 veadk.cloud.harness_app，自带上述三类路由及 codex 运行时依赖）。

参数	说明	默认值
`<name>`	项目 / Harness 名称，决定目录名。仅允许字母、数字、`_`、`-`。	必填
`--template`, `-t`	模板类型，Harness 场景固定为 `harness`。	—
`--directory`	创建项目的目标目录。	当前目录

bash

agentkit init my-harness --template harness
cd my-harness
cp .env.example .env          # 填入火山引擎 AK/SK

生成的目录结构：

plaintext

my-harness/
├── .env.example   # 复制为 .env，填入 VOLCENGINE_ACCESS_KEY / VOLCENGINE_SECRET_KEY
└── Dockerfile     # 云端构建 veadk.cloud.harness_app 服务

2. add harness —— 生成 / 更新 Harness 配置

agentkit add harness --name <name> [options] 在 --directory 下写入 <name>.harness.json，声明 Harness 的默认装配。对同一 --name 重复执行会增量合并到现有文件，便于逐步完善配置。每个选项只在显式传入时写入；--tools / --skills / --allowed-id 接受逗号分隔列表。

2.1 核心与组件参数

参数	说明	取值
`--name`	（必填） Harness 名称，决定输出文件 `<name>.harness.json`。	字母 / 数字 / `_` / `-`
`--model-name`	推理模型名。	如 `doubao-seed-1-6-250615`
`--system-prompt`	系统提示词 / instruction。	任意字符串
`--description` / `--desc`	Agent 描述，初始化 Agent 时定义（如用于 A2A 发现）。	任意字符串
`--tools`	内置工具名，逗号分隔。	如 `web_search,web_fetch`
`--skills`	技能 Hub 名，逗号分隔。	如 `data-visualization-cloud`
`--runtime`	Agent 运行时后端。	`adk`（默认）/ `codex`
`--structured-tool-calls` / `--no-structured-tool-calls`	是否要求模型输出可执行的结构化工具调用。	显式传入时写入
`--include-tools-every-turn` / `--reuse-tool-context`	是否在每轮模型调用都注入工具定义。	显式传入时写入
`--registry`	A2A registry URI；传 `default` 使用默认 A2A registry；传 `disabled` 可显式关闭 registry。	—
`--registry-space-id`	A2A Registry SpaceId。	—
`--registry-space-name`	A2A Registry Space 名称；CLI 会调用 `ListA2aSpaces` 解析为 SpaceId 后写入配置。	—
`--registry-top-k`	registry 检索候选 AgentCard 数量。	—
`--registry-endpoint`	A2A registry OpenAPI endpoint。	—
`--registry-region`	A2A registry OpenAPI region。	—
`--knowledgebase-type`	知识库后端。	`viking` / `opensearch` / `redis` / `tos_vector` / `context_search`
`--long-term-memory-type`	长期记忆后端。	`viking` / `opensearch` / `redis` / `mem0`
`--short-term-memory-type`	短期记忆后端。	`local`（默认）/ `sqlite` / `mysql` / `postgresql`
`--discovery-url`	OIDC discovery URL，启用 OAuth2/JWT 鉴权。	见「7. 鉴权」
`--allowed-id`	允许的客户端 ID，逗号分隔。	见「7. 鉴权」
`--register-self`	将当前项目已部署的 Harness 注册到 A2A registry。会读取 `harness.json[name].url` 和 `runtime_id`。	需先 `deploy`
`--register-space-id`	`--register-self` 使用的 A2A SpaceId；未传时可从 spec 的 `registry.space_id` 读取。	—
`--register-space-name`	`--register-self` 使用的 A2A Space 名称；CLI 会调用 `ListA2aSpaces` 解析为 SpaceId。	—
`--register-network-type`	注册到 A2A registry 的网络类型。	`public` / `private`
`--directory`	写入 `<name>.harness.json` 的目录。	当前目录

内置工具名以 VeADK veadk/tools/__init__.py 的 _BUILTIN_TOOLS 为准（如 web_search、web_fetch、run_code、link_reader 等）；技能名为技能 Hub 的下载路径，可带命名空间（如 clawhub/<org>/<skill>）。

2.2 组件连接参数

各组件除 type 外，还可传入其连接参数；这些参数会被写入对应组件块，部署时映射为运行时环境变量（详见「6. memory / knowledgebase」）。

组件	连接参数（旗标前缀）
知识库	`--knowledgebase-project` / `-region` / `-host` / `-port` / `-username` / `-password` / `-use-ssl` / `-cert-path` / `-secret-token` / `-db`
长期记忆	`--long-term-memory-project` / `-region` / `-host` / `-port` / `-username` / `-password` / `-db` / `-api-key` / `-api-key-id` / `-project-id` / `-base-url`
短期记忆	`--short-term-memory-host` / `-port` / `-user` / `-password` / `-database` / `-charset`

2.3 A2A Registry 与工具调用配置

Harness 的 A2A Registry 默认不开启；只有显式传入 --registry 或 --registry-* 参数时，CLI 才会写入 registry 配置，并把 registry.type 设为 agentkit_a2a。最小开启方式是提供 space_id：

bash

agentkit add harness --name my-harness \
  --registry-space-id as-xxx

如果只知道空间名称，也可以使用 --registry-space-name。CLI 会通过 AgentKit OpenAPI ListA2aSpaces 查询空间列表，按 Name 精确匹配后取返回项的 Id 写入 registry.space_id；如果找不到或匹配到多个同名空间，会直接报错。解析时使用 --registry-region / --registry-endpoint 指定的 OpenAPI 地址，未指定时默认按 cn-beijing 推导。

bash

agentkit add harness --name my-harness \
  --registry-space-name my-space \
  --registry-top-k 3 \
  --registry-region cn-beijing

如果要使用 AgentKit 默认 A2A Registry，可以直接传 default。它等价于 agentkit://a2a-registry?space_name=Default&region=cn-beijing&endpoint=https://open.volcengineapi.com/，CLI 会把 Default space name 解析为 space id 后写入 spec：

bash

agentkit add harness --name my-harness --registry default

当 registry 最终解析出 A2A SpaceId 后，CLI 会额外调用 UpdateA2aSpace 并设置 IntentEnabled=true，开启该空间的语义检索能力。调用方需要具备 agentkit:UpdateA2aSpace 权限。

部署后的 Harness Runtime 在每轮用户对话开始前，会用用户原始输入的前 2048 个 UTF-8 bytes 调用 SearchAgentCards；对本轮返回的每个 AgentCard，再调用 GetA2aAgent 获取 endpoint 与鉴权信息，并临时包装为本轮可用的 remote_a2a_* 工具。这些动态工具只对当前轮次生效，不写回 spec，也不污染已部署的基础 Agent。

远程 Agent 的调用鉴权由 Runtime 自动处理：apiKey 类型 AgentCard 会按 securitySchemes 中声明的 header 注入；oauth2 且声明 clientCredentials.tokenUrl 的 AgentCard 会从 token URL 解析火山引擎 Identity UserPool，查询其中的 MACHINE_TO_MACHINE client，使用 client_credentials 换取 access token，并以 Authorization: Bearer <access_token> 调用远程 A2A endpoint。通常无需额外配置；如果 registry endpoint 不是公网 OpenAPI 网关且无法同时访问 Identity OpenAPI，可用 REGISTRY_ID_ENDPOINT / AGENTKIT_ID_ENDPOINT 指定 Identity OpenAPI 地址。

--registry-endpoint 用于指定 Harness Runtime 后续访问 A2A Registry OpenAPI 的地址。通常不传时会按 region 推导默认 endpoint；如果部署后的运行时环境无法解析 region 专属域名，或需要统一走火山引擎公网 OpenAPI 网关，可以显式设置为 https://open.volcengineapi.com/：

bash

agentkit add harness --name my-harness \
  --registry-space-id as-xxx \
  --registry-region cn-beijing \
  --registry-endpoint https://open.volcengineapi.com/

需要注意：--registry-endpoint 会写入 <name>.harness.json，部署后由云端 Runtime 使用；--register-endpoint 只影响本次 --register-self 在本地调用 ListA2aSpaces / CreateA2aAgent 的 OpenAPI 地址。配置 registry endpoint 后需要重新 agentkit deploy --harness <name> 才会影响云端运行时。

也可以使用 URI 一次性写入：

bash

agentkit add harness --name my-harness \
  --registry "agentkit://a2a-registry?space_id=as-xxx&top_k=3&endpoint=https%3A%2F%2Fopen.volcengineapi.com%2F&region=cn-beijing"

URI 里也支持用 space_name 代替 space_id：

bash

agentkit add harness --name my-harness \
  --registry "agentkit://a2a-registry?space_name=my-space&top_k=3&region=cn-beijing"

如果后续要关闭已经配置过的 registry，使用：

bash

agentkit add harness --name my-harness --registry disabled

该命令会让 spec 不再保留 registry 配置，运行时也就不再启用 agentkit_a2a registry。由于 add harness 只修改本地 <name>.harness.json，关闭或重新开启 registry 后都需要重新执行 agentkit deploy --harness <name>，云端运行时才会使用新配置。

当 Harness 需要通过 registry 检索并调用其他 A2A Agent 时，建议同时开启：

bash

agentkit add harness --name my-harness \
  --registry-space-id as-xxx \
  --structured-tool-calls \
  --include-tools-every-turn

这两个参数会写入 <name>.harness.json：

json

{
  "structured_tool_calls": true,
  "include_tools_every_turn": true
}

部署时，这些字段会通过通用展平规则映射成运行时环境变量：

text

STRUCTURED_TOOL_CALLS=true
INCLUDE_TOOLS_EVERY_TURN=true

structured_tool_calls 的作用是要求模型以结构化格式输出工具调用，而不是只在自然语言里描述“应该调用某个工具”。A2A registry 返回的候选 AgentCard 最终会作为可调用工具进入 Harness；启用结构化工具调用后，运行时更容易稳定解析出工具名和参数，并执行对应的 A2A 调用。

底层实现上，structured_tool_calls 会影响 VeADK Harness Runtime 初始化 Agent 时的 enable_responses 参数：

python

Agent(
  ...,
  enable_responses=config.structured_tool_calls,
  enable_responses_cache=not config.include_tools_every_turn,
)

VeADK Agent 在创建模型客户端时会根据 enable_responses 选择不同实现：

structured_tool_calls=false：使用默认 LiteLlm，走 LiteLLM/Chat Completions 风格的调用链。
structured_tool_calls=true：使用 ArkLlm，走火山 Ark Responses API 调用链。

因此这个配置会改变模型请求的底层协议。默认 LiteLlm 分支更接近通用 LiteLLM 适配层；开启后使用 ArkLlm，运行时会把 ADK 的 LlmRequest 转成 Ark Responses API 参数，包括 input、instructions、tools、text 等字段。工具声明会被转换成 Ark Responses API 的 function tool 参数，模型返回的 ResponseFunctionToolCall 再被转换回 ADK 可执行的工具调用结果。这个转换链使 registry 动态发现的 AgentCard 能以明确的工具名和参数参与执行，减少自然语言解析造成的不稳定。

ArkLlm 还会处理 Responses API 的 previous_response_id。当启用 responses cache 时，多轮调用可以通过上一轮响应 ID 续接上下文；但 Ark Responses API 对“带 previous_response_id 的后续请求继续携带 tools”存在限制，因此运行时可能在后续轮次移除 tools。include_tools_every_turn=true 会让 Harness 传入 enable_responses_cache=false，不依赖 previous_response_id 缓存续接，而是在每轮请求中重新携带工具定义。这也是 registry 场景通常建议同时开启 structured_tool_calls 和 include_tools_every_turn 的原因：前者切到 Ark Responses API 以获得结构化工具调用，后者确保多轮过程中工具定义持续可见。

include_tools_every_turn 的作用是在每一轮模型请求中都注入当前可用工具定义。Registry 工具通常依赖运行时检索结果，工具集合可能随上下文变化；如果只在首轮提供工具定义，多轮推理时模型可能忘记或误用这些工具。开启该参数可以提高多轮任务中继续发现、选择和调用 A2A Agent 的稳定性。

这两个参数不是所有 Harness 都必须开启；如果 Harness 不使用 registry 或不依赖模型主动选择工具，可以保持默认不写入。对于需要通过 registry 做动态 Agent 发现和协作的场景，建议开启。

2.4 例子

bash

# 最小：模型 + 工具 + 系统提示词
agentkit add harness --name my-harness \
  --model-name doubao-seed-1-6-250615 \
  --tools web_search,web_fetch \
  --system-prompt "You are a helpful assistant."

# 增量补充技能与运行时（合并进同名文件）
agentkit add harness --name my-harness --skills data-visualization-cloud --runtime adk

# 开启 A2A Registry，并增强多轮工具调用稳定性
agentkit add harness --name my-harness \
  --registry-space-id as-xxx \
  --registry-top-k 3 \
  --registry-endpoint https://open.volcengineapi.com/ \
  --registry-region cn-beijing \
  --structured-tool-calls \
  --include-tools-every-turn

# 使用 A2A Space 名称开启 Registry；CLI 会解析并写入 space_id
agentkit add harness --name my-harness \
  --registry-space-name my-space \
  --registry-top-k 3 \
  --registry-region cn-beijing

# 使用默认 A2A Registry
agentkit add harness --name my-harness --registry default

# 关闭已配置的 A2A Registry
agentkit add harness --name my-harness --registry disabled

# 注册本项目已部署的 harness：从 harness.json 读取 url/runtime_id
agentkit add harness --name my-harness \
  --register-self \
  --register-space-id as-xxx \
  --register-network-type public

# 也可以使用 A2A Space 名称注册
agentkit add harness --name my-harness \
  --register-self \
  --register-space-name my-space \
  --register-network-type public

# 配置知识库（Viking）+ 长期记忆（mem0）+ 短期记忆（PostgreSQL）
agentkit add harness --name my-harness \
  --knowledgebase-type viking --knowledgebase-project my-proj --knowledgebase-region cn-beijing \
  --long-term-memory-type mem0 --long-term-memory-api-key "$MEM0_API_KEY" \
  --long-term-memory-project-id "$MEM0_PROJECT_ID" \
  --short-term-memory-type postgresql --short-term-memory-host pg.example.com \
  --short-term-memory-user agent --short-term-memory-password "$PG_PASSWORD" \
  --short-term-memory-database harness

执行后 my-harness.harness.json 形如：

json

{
  "harness_name": "my-harness",
  "runtime": "adk",
  "short_term_memory": { "type": "local" },
  "model": { "name": "doubao-seed-1-6-250615" },
  "system_prompt": "You are a helpful assistant.",
  "tools": ["web_search", "web_fetch"]
}

3. deploy —— 部署为云端运行时

agentkit deploy --harness <name> [options] 读取当前目录的 <name>.harness.json，将其展平为运行时环境变量，执行云端构建 + 部署（无需本地 Docker），并为运行时打上 agentkit:agenttype=harness 标签。成功后把运行时坐标回写到同目录的 harness.json 注册表，供按名调用。

参数	说明	默认值
`--harness`	（必填）要部署的 Harness 名称，对应 `<name>.harness.json`。	—
`--region`	AgentKit 区域。	`cn-beijing` 或 `VOLCENGINE_REGION`
`--volcengine-access-key`	火山引擎 Access Key。	环境变量 `VOLCENGINE_ACCESS_KEY`
`--volcengine-secret-key`	火山引擎 Secret Key。	环境变量 `VOLCENGINE_SECRET_KEY`
`--discovery-url`	OIDC discovery URL；设置后运行时改用 `custom_jwt` 网关鉴权。	见「7. 鉴权」
`--allowed-id`	允许的客户端 ID，逗号分隔（custom_jwt）。	见「7. 鉴权」
`--yes`, `-y`	同名运行时已存在时直接更新为新版本，不交互询问。	`false`

凭证安全：.env 中的火山 AK/SK 仅用于本地发起部署，不会写入镜像或运行时明文。

harness.json 注册表条目（按鉴权类型）：

json

{
  "my-harness": { "url": "https://xxx.apigateway-cn-beijing.volceapi.com", "key": "...", "runtime_id": "r-xxx" }
}

custom_jwt 部署的条目不含 key，而记录 auth_type / discovery_url / allowed_ids（JWT 由调用方每次请求携带）。

bash

# 在 harness 目录下执行
agentkit deploy --harness my-harness

# 指定区域；同名已存在时直接更新
agentkit deploy --harness my-harness --region cn-beijing --yes

4. register-self —— 注册本项目 Harness 到 A2A registry

注册当前项目对应的 Harness 时，使用 add harness --register-self。该命令会从 --directory 下的 harness.json 读取 <name> 对应条目的 url 和 runtime_id；如果条目不存在，或缺少 url / runtime_id，会直接报错提示先部署或修复 harness.json。

bash

agentkit add harness --name my-harness \
  --register-self \
  --register-space-id as-xxx \
  --register-network-type public

可选参数：

参数	说明	默认值
`--register-space-id`	A2A SpaceId。未传时可从 spec 的 `registry.space_id` 读取。	—
`--register-network-type`	Runtime 网络地址类型。	`public`
`--register-endpoint`	AgentKit OpenAPI endpoint。	按 region 推导
`--register-region`	AgentKit OpenAPI region。	`AGENTKIT_REGION` / `VOLCENGINE_REGION` / `cn-beijing`
`--register-tag`	`KEY=VALUE` 标签，可重复。	—

5. invoke harness —— 按名调用

agentkit invoke harness <name> "<prompt>" [options] 在 --directory（默认当前目录）下的 harness.json 注册表中按名查找运行时并发起调用。通过 --protocol 选择传输方式：

run_sse（默认）：调用 ADK 的 /run_sse，流式返回。其 app_name 固定为 harness；user_id 在携带 JWT（custom_jwt）时取其 sub 声明（与登录身份绑定），否则随机生成。渲染上：等待与推理阶段显示一个 thinking loading 动画（模型 thought 不展示），收到答案后空一行逐字流式输出回答正文；工具事件与末尾重复的聚合事件不显示；--raw 可打印底层原始 SSE。
invoke：POST /harness/invoke，非流式，返回完整结果（含错误透传）。

两种方式的 session_id 都取 --session-id，未指定时随机生成 s-<id>（行为一致）；run_sse 调用前会创建该 session（幂等：已存在也不影响）。

两种方式都支持一次性覆写（--system-prompt / --model-name / --tools / --skills / --runtime / registry 参数）；覆写为叠加在本次调用上的临时值，不写回 spec、不改动运行时（工具 / 技能为增量加入）。

鉴权（两种传输方式统一）：--apikey/-ak 显式传入时优先；否则对 custom_jwt 的 Harness 自动读取 agentkit login 会话中的 OIDC id_token 作为 Bearer（自动续期，401 时强制刷新并重试一次）——因此 custom_jwt 的 Harness 无需手动传 -ak；对 key_auth 的 Harness 使用注册表中的静态 key（key_auth 鉴权器会拒绝 JWT，故不会强塞 id_token）。

参数	说明	默认值 / 取值
`<name>`	（必填）已部署的 Harness 名称（注册表键）。	—
`<message>`	（必填）发送给 Harness 的提示词。	—
`--protocol`	传输方式。	`run_sse`（默认）/ `invoke`
`--directory`	`harness.json` 注册表所在目录。	当前目录
`--user-id`	运行的 user_id（仅 `invoke`；`run_sse` 取 JWT `sub` 或随机生成）。	`agentkit_user`
`--session-id`	运行的 session_id（两种传输方式一致）。	未指定时随机 `s-<id>`
`--max-llm-calls`	本次调用的最大 LLM 调用次数（仅 `invoke`）。	不限
`--system-prompt`	覆写系统提示词。	—
`--model-name`	覆写模型名。	—
`--tools`	覆写工具（逗号分隔，增量加入）。	—
`--skills`	覆写技能（逗号分隔，增量加入）。	—
`--runtime`	覆写运行时后端。	`adk` / `codex`
`--registry`	覆写 A2A registry。支持 `default`、`agentkit://a2a-registry?space_id=xxx&top_k=3`、`agentkit://a2a-registry?space_name=xxx` 或 `http(s)` URL。	—
`--registry-space-id`	覆写 A2A registry space id。	—
`--registry-space-name`	覆写 A2A registry space name。CLI 会调用 `ListA2aSpaces` 解析为 space id 后传给运行时。	—
`--registry-top-k`	覆写 registry 检索 AgentCard 数量。	—
`--registry-endpoint`	覆写 A2A registry OpenAPI endpoint。	—
`--registry-region`	覆写 A2A registry OpenAPI region。	—
`--apikey`, `-ak`	Bearer Token 覆写（如 custom_jwt 的用户 JWT）。	自动鉴权或注册表 `key`
`--raw`	打印原始响应（`InvokeHarnessResponse` / SSE）。	`false`

--max-llm-calls 不属于 ADK run_sse 请求，故仅在 invoke 模式生效；在 run_sse 模式传入会被忽略并提示。

当本次调用通过 --registry / --registry-space-id / --registry-space-name 指定了 A2A SpaceId 时，CLI 同样会先调用 UpdateA2aSpace 开启 IntentEnabled=true，再把 registry 覆写发送给 Harness Runtime。

本次调用若命中 OAuth 类型 remote-agent，鉴权行为与部署时的 registry 配置一致：Runtime 会在 GetA2aAgent 后根据 AgentCard 的 oauth2.clientCredentials.tokenUrl 自动获取 access token，并在动态 remote_a2a_* 工具执行 message/send / tasks/get 时附加 Bearer token。

bash

# 基础调用（run_sse，默认，流式）
agentkit invoke harness my-harness "今天杭州天气如何？"

# 一次性覆写系统提示词
agentkit invoke harness my-harness "2+2=?" --system-prompt "请简洁作答。"

# 指定 session（未指定则随机生成；同名 session 幂等复用以延续上下文）
agentkit invoke harness my-harness "继续上文" --session-id sess-001

# 覆写模型与工具
agentkit invoke harness my-harness "帮我查一下杭州天气" \
  --model-name doubao-seed-1-6-250615 --tools web_search,web_fetch

# 按名调用 harness，并在本次调用中追加 registry / 模型 / 工具 / 技能覆写
agentkit invoke harness paper-researcher \
  --model-name doubao-seed-2-0-code-preview-260215 \
  --tools web_search,run_code,link_reader \
  --skills data-visualization-cloud,byted-arkclaw-paper-research,web-scraper \
  --registry "agentkit://a2a-registry?space_id=as-xxx&top_k=5&region=cn-beijing" \
  "Plot the performance comparison between different transformer models."

# 本次调用使用 A2A Space 名称覆写 registry；CLI 会解析成 space id
agentkit invoke harness my-harness \
  --registry-space-name my-space \
  --registry-top-k 1 \
  --registry-region cn-beijing \
  --registry-endpoint https://open.volcengineapi.com/ \
  "帮我找一个财务报销专家"

# URI 中也可以使用 space_name；不支持 registry_space_name 等别名
agentkit invoke harness my-harness \
  --registry "agentkit://a2a-registry?space_name=my-space&top_k=1&region=cn-beijing&endpoint=https%3A%2F%2Fopen.volcengineapi.com%2F" \
  "帮我找一个财务报销专家"

# 使用默认 A2A Registry 作为本次调用覆写
agentkit invoke harness my-harness \
  --registry default \
  "帮我找一个财务报销专家"

# 改用 invoke（非流式 /harness/invoke），并限制最大 LLM 调用次数
agentkit invoke harness my-harness "规划一次多步研究任务。" --protocol invoke --max-llm-calls 10

# OAuth（custom_jwt）的 Harness：默认自动使用 `agentkit login` 的 JWT，无需 -ak
agentkit invoke harness my-harness "你好"
# 如需覆写凭证可显式传入
agentkit invoke harness my-harness "你好" -ak "<user-oauth-jwt>"

错误透传：当 Harness 返回失败（工具不支持 / 技能加载失败 / 运行期错误等）时，CLI 以红色高亮原样回显错误信息并以非 0 退出。

6. memory / knowledgebase 配置

知识库与记忆在 add harness 时声明、deploy 时绑定到基础 Agent。部署时各组件的 type 映射为选择器环境变量，连接参数映射为 VeADK 的 DATABASE_* 环境变量，火山凭证复用 .env 的 VOLCENGINE_*。

组件	选择器 env	支持后端	连接参数 env 前缀
知识库	`KNOWLEDGEBASE_TYPE`	`viking` / `opensearch` / `redis` / `tos_vector` / `context_search`	`DATABASE_VIKING_` / `DATABASE_OPENSEARCH_` / `DATABASE_REDIS_*`
长期记忆	`LONG_TERM_MEMORY_TYPE`	`viking` / `opensearch` / `redis` / `mem0`	同上 + `DATABASE_MEM0_*`
短期记忆	`SHORT_TERM_MEMORY_TYPE`	`local` / `sqlite` / `mysql` / `postgresql`	`DATABASE_MYSQL_` / `DATABASE_POSTGRESQL_`（`local`/`sqlite` 无需参数）

bash

# 只挂知识库（Viking）
agentkit add harness --name my-harness \
  --knowledgebase-type viking --knowledgebase-project my-proj --knowledgebase-region cn-beijing

memory / knowledgebase 是部署时绑定的：invoke / run_sse 的一次性覆写不包含 memory / knowledgebase——调用时用的始终是部署时配置的那套；要更改需修改 spec 后重新部署。

7. 鉴权

部署后默认采用 API Key（key_auth） 鉴权：注册表记录 key，调用时 CLI 自动以 Authorization: Bearer <key> 发送。

若希望用火山引擎用户池签发的 JWT 进行网关鉴权（custom_jwt），在 add harness 或 deploy 时提供 --discovery-url 与 --allowed-id：

参数	说明
`--discovery-url`	用户池 OIDC discovery 地址，如 `https://userpool-<id>.userpool.auth.id.cn-beijing.volces.com/.well-known/openid-configuration`
`--allowed-id`	允许访问该运行时的客户端 ID（JWT audience），逗号分隔

二者必须同时提供，否则部署时快速失败。采用 custom_jwt 后，注册表条目不含 key，调用时需通过 -ak <jwt>（或 --headers '{"Authorization":"Bearer <jwt>"}'）携带用户池签发的 JWT（CLI 不负责签发）。

bash

# 部署为 OAuth2/JWT 鉴权
agentkit deploy --harness my-harness \
  --discovery-url "https://userpool-<id>.userpool.auth.id.cn-beijing.volces.com/.well-known/openid-configuration" \
  --allowed-id "<client-id-1>,<client-id-2>"

8. list harness —— 列出已部署的 Harness

agentkit list harness 列出当前凭证下所有带 agentkit:agenttype=harness 标签的运行时。

参数	说明	默认值
`--region`	区域覆盖。	环境变量 / 全局配置
`--output`	输出格式 `table` / `json` / `yaml`。	`table`
`--quiet`, `-q`	仅打印 RuntimeId。	`false`
`--no-color`, `-nc`	关闭彩色输出。	`false`
`--limit`, `-l`	每批拉取的运行时数量。	`50`

bash

agentkit list harness
agentkit list harness --output json --region cn-beijing

9. list sessions —— 列出某 Harness 的会话

agentkit list sessions --harness <name> 列出某个已部署 harness 运行时上、某个用户的对话会话。它通过 harness.json 解析出运行时地址与凭证，直接调用运行时的 ADK 数据面端点：

text

GET {harness_url}/apps/harness/users/{user_id}/sessions

与 list harness（控制面，AK/SK 调火山 ListRuntimes）不同，本命令是数据面调用，寻址方式与 invoke harness 一致（按名从 harness.json 解析、用 harness 凭证鉴权）。

user_id 的确定方式

ADK 的会话列表接口把 user_id 作为必填路径参数，没有"列出所有用户会话"的能力。因此 user_id 必须能被确定，按以下优先级：

显式 --user-id <id>；
未指定时，从 harness 凭证的 JWT sub 解出——
- custom_jwt（OAuth）harness：默认使用 agentkit login 的 id_token（或 -ak 传入的 JWT），其 sub 即用户身份；
- key_auth harness：凭证是不透明 API Key、不是 JWT，无法解出 user_id，此时必须显式 --user-id，否则快速失败。

参数

参数	说明	默认值
`--harness <name>`	（必填） harness 名称，从 `harness.json` 解析。	—
`--user-id <id>`	要查询的用户；缺省时尝试从凭证 JWT 的 `sub` 推导。	由 JWT 推导
`--apikey`, `-ak <token>`	Bearer token（如 custom_jwt harness 的 OIDC JWT），覆盖 registry 中的凭证。	注册表凭证
`--directory <dir>`	`harness.json` 所在目录。	`.`（当前目录）
`--output`	输出格式 `table` / `json` / `yaml`。	`table`
`--quiet`, `-q`	仅打印会话 id。	`false`
`--no-color`, `-nc`	关闭彩色输出。	`false`

表格输出包含 SessionId、Events（事件数）、LastUpdate（最近更新时间）等列。

例子

bash

# custom_jwt（OAuth）harness：已 agentkit login，user_id 自动取自 JWT sub
agentkit list sessions --harness my-harness

# 显式指定用户（key_auth harness 必须这样）
agentkit list sessions --harness my-harness --user-id alice

# 传入 JWT 覆盖凭证（user_id 取自该 JWT 的 sub）
agentkit list sessions --harness my-harness -ak "<oidc-jwt>"

# 仅打印会话 id / JSON 输出
agentkit list sessions --harness my-harness --user-id alice --quiet
agentkit list sessions --harness my-harness --user-id alice --output json

Harness Beta ​

1. init —— 生成 Harness 项目骨架 ​

2. add harness —— 生成 / 更新 Harness 配置 ​

2.1 核心与组件参数 ​

2.2 组件连接参数 ​

2.3 A2A Registry 与工具调用配置 ​

2.4 例子 ​

3. deploy —— 部署为云端运行时 ​

4. register-self —— 注册本项目 Harness 到 A2A registry ​

5. invoke harness —— 按名调用 ​

6. memory / knowledgebase 配置 ​

7. 鉴权 ​

8. list harness —— 列出已部署的 Harness ​

9. list sessions —— 列出某 Harness 的会话 ​

user_id 的确定方式 ​

参数 ​

例子 ​

Harness Beta

1. init —— 生成 Harness 项目骨架

2. add harness —— 生成 / 更新 Harness 配置

2.1 核心与组件参数

2.2 组件连接参数

2.3 A2A Registry 与工具调用配置

2.4 例子

3. deploy —— 部署为云端运行时

4. register-self —— 注册本项目 Harness 到 A2A registry

5. invoke harness —— 按名调用

6. memory / knowledgebase 配置

7. 鉴权

8. list harness —— 列出已部署的 Harness

9. list sessions —— 列出某 Harness 的会话

user_id 的确定方式

参数

例子