配置 Agent（cloudbase-agent 模板）

用官方 cloudbase-agent 模板创建的 Agent，人设（system prompt）、模型、工具都通过配置项设置。本文说明配置放在哪、怎么改、怎么生效。

配置的四个来源

运行时按下面的顺序查找配置，命中即停止：

优先级	来源	适用场景
1	AGENT_CONFIG / AGENT_CONFIG_B64 环境变量	完整 JSON 配置，平台写入
2	agent.yaml / agent.yml（工作目录或 /var/user/）	本地开发、代码里带完整配置
3	AGENT_NAME / AGENT_MODEL / AGENT_SYSTEM 环境变量	只改人设和模型
4	内置默认值	未做任何配置时

内置默认值：

name    = open-managed-agent
model   = hy3-preview
system  = You are a helpful assistant.

控制台新建的 Agent 默认不带 agent.yaml，也不写 AGENT_CONFIG，因此走的是第 3、4 层——设置环境变量就能改人设，不需要改代码。

只改人设和模型：设置环境变量

tcb agent update <agentId> \
  -e <envId> \
  --env "CLOUDBASE_ENV_ID=<envId>,CLOUDBASE_APIKEY=<环境 API Key>,AGENT_MODEL=deepseek-v4-pro,AGENT_SYSTEM=<URL 编码后的人设>"

改完立即生效，不需要重新部署代码。

有两个地方容易出错：

--env 是整体替换，不是追加。 命令里必须带上 Agent 原有的 CLOUDBASE_ENV_ID 和 CLOUDBASE_APIKEY——控制台创建的 Agent 默认就带这两个。漏掉环境 ID，Agent 会直接报 toKernelAgentConfig: envId is required。执行前可以先查当前值：

tcb fn detail <agentId> -e <envId> --json

AGENT_SYSTEM 的值需要 URL 编码。 运行时会对它做一次 decodeURIComponent，直接填中文原文会解析异常：

node -e "console.log(encodeURIComponent('你是一位电商客服，只回答与订单和物流有关的问题。'))"

另外，默认模型 hy3-preview 需要环境已开通。未开通时调用会返回 AI_MODEL_NOT_SUPPORTED，显式设置 AGENT_MODEL 即可。可用模型见接入大模型。

完整配置：agent.yaml

需要配置工具、MCP server、审批策略时，在代码根目录放一个 agent.yaml：

name: my-agent
model: deepseek-v4-pro
system: |
  你是一位电商客服。
  只回答与订单、物流、退换货有关的问题，其他问题礼貌拒绝。
description: 电商客服 Agent

# 工具
tools:
  # 内置工具（bash / read / write / edit / glob / grep）
  - type: agent_toolset
    default_config:
      enabled: true
      permission_policy:
        type: always_ask       # always_ask 触发人工审批；always_allow 直接执行
    configs:
      - name: bash
        permission_policy:
          type: always_ask

  # 客户端自定义工具（由调用方执行并回传结果）
  - type: custom
    name: getClientInfo
    description: 获取客户端用户信息
    input_schema:
      type: object
      properties:
        query:
          type: string
      required: [query]

  # 引用下面声明的 MCP server
  - type: mcp_toolset
    mcp_server_name: my-mcp

mcp_servers:
  - type: url
    name: my-mcp
    url: https://example.com/mcp

字段说明

字段	必填	说明
name	是	Agent 名称
model	是	模型 ID 字符串；或 { id, apiKey, apiBaseUrl, options } 接入自带 endpoint 的模型
system	是	系统提示词，即 Agent 的人设与行为约束
description	否	Agent 描述
tools	否	工具配置，三种 type：agent_toolset（内置工具）、custom（客户端工具）、mcp_toolset（引用 MCP server）
mcp_servers	否	MCP server 声明，{ type: url, name, url }
skills	否	Skill 列表，{ source }
metadata	否	自定义键值对
sessions_collection	否	会话存储的数据库集合名，默认 acp_sessions

内置工具名：bash、read、write、edit、glob、grep。

permission_policy.type 取值：always_ask（调用前触发人工审批）、always_allow（直接执行）。

字段名不要和 OAK SDK 混用

agent.yaml 用下划线命名，与直接调用 OAK SDK createAgent() 时的驼峰参数不是同一套：

agent.yaml	createAgent()
system	systemPrompt
mcp_servers	mcpServers

写错的字段会被忽略且不报错，表现为配置"没生效"——人设会回落到默认的 You are a helpful assistant.。直接用 SDK 开发的写法见 OpenAgentKernel。

欢迎语与开场问题

这两项属于界面展示数据，不建议写死在 Agent 配置里。推荐存到数据库的配置表、由前端读取渲染，改配置即时生效。做法见 OpenAgentKernel — 动态配置欢迎语与开场问题。

相关文档

• OpenAgentKernel（官方 SDK）
• ACP 协议
• 接入大模型