> ## 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` 里，由 CLI 直接构建并部署为运行时。整个闭环只围绕一个文件展开——初始化、配置、部署、调用，再回到配置持续迭代。

<Note>
  开始前请先配置 AK/SK，或通过 [SSO 登录](/productions/agentkit-cli/preview/zh/commands/auth)获取短期 STS 凭证。`harness deploy` 需要控制面凭据；`harness invoke` 会用控制面凭据解析 Runtime，并可为 `custom_jwt` Runtime 额外传入用户 token。配置方法见[快速开始](/productions/agentkit-cli/preview/zh/quickstart)的「鉴权」一节。
</Note>

<Warning>
  `harness deploy` 会在云端构建镜像并创建或更新 Runtime，可能产生费用；更新已有 Runtime 还会改变其线上行为。部署前确认项目、地域、配置和凭证引用，并在业务低风险时段发布变更。
</Warning>

<Steps>
  <Step title="初始化 harness">
    创建一个 harness 目录，其中包含 `harness.yaml` 与 `.env.example`。

    ```bash lines theme={null}
    agentkit harness init my-harness
    cd my-harness
    ```
  </Step>

  <Step title="配置智能体">
    用 `harness set` 逐项写入字段。仅显式传入的标志会被修改，因此可以分多次补充配置。

    ```bash lines theme={null}
    agentkit harness set \
      --name my-harness \
      --model-name "your-model-name" \
      --system-prompt "你是一个简洁、乐于助人的智能体。"
    ```

    <Tip>
      配置知识库、记忆等组件时，先设置其 `--<组件>-type`，再补充连接参数；传入空字符串 `""` 可禁用某个组件。不带任何标志运行 `agentkit harness set` 会列出当前字段。完整字段见[Harness](/productions/agentkit-cli/preview/zh/commands/harness)。
    </Tip>
  </Step>

  <Step title="核对云环境与组件权限">
    将 `your-model-name` 替换为账号可调用的模型或端点 ID。默认直接模型调用需要 Runtime 角色具备相应模型访问权限；部署成功不代表模型已授权。先以无外部工具的最小配置验证回复，再添加知识库、MCP 和记忆

    本例使用火山引擎北京区域。使用 BytePlus 时，初始化命令改为 `agentkit --provider byteplus harness init my-harness --region ap-southeast-1`，后续部署与查询均使用相同区域。数据库密码和 MCP 凭据可在 `harness.yaml` 中引用 `${VAR}`，实际值放在未提交的 `.env` 中
  </Step>

  <Step title="构建并部署">
    根据 `harness.yaml` 在云端构建镜像，并创建或更新运行时。

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

  <Step title="调用运行时">
    按名称调用刚部署的运行时，CLI 会自动解析端点与鉴权，并使用已配置的 AK/SK 或当前 SSO 登录 profile 的有效 STS 凭证。

    ```bash lines theme={null}
    agentkit runtime show my-harness
    agentkit harness invoke my-harness "你好，介绍一下你自己"
    ```
  </Step>

  <Step title="迭代">
    修改配置后重新部署即可发布新版本；运行时行为异常时，查看实例日志定位问题。

    ```bash lines theme={null}
    agentkit harness set --name my-harness --system-prompt "更换后的指令。"
    agentkit harness deploy
    agentkit runtime logs my-harness --limit 200
    ```
  </Step>
</Steps>

不再需要该运行时时，将其删除以释放资源：

<Warning>
  删除 Runtime 不可恢复，并会停止线上调用。执行前确认名称、项目和地域，保留需要的配置、日志与业务数据。
</Warning>

```bash lines theme={null}
agentkit runtime delete my-harness -y
```

需要自定义逻辑、工具或多智能体编排时，改用[高代码智能体](/productions/agentkit-cli/preview/zh/workflows/high-code)。