Configuring an Agent (cloudbase-agent template)

For Agents created from the official cloudbase-agent template, the persona (system prompt), model, and tools are all set through configuration. This page explains where that configuration lives, how to change it, and how changes take effect.

The four configuration sources

At startup the runtime looks for configuration in the following order and stops at the first match:

Priority	Source	When it applies
1	AGENT_CONFIG / AGENT_CONFIG_B64 environment variable	Full JSON configuration, written by the platform
2	agent.yaml / agent.yml (working directory or /var/user/)	Local development, or full configuration kept in code
3	AGENT_NAME / AGENT_MODEL / AGENT_SYSTEM environment variables	Changing only the persona and model
4	Built-in defaults	Nothing configured

Built-in defaults:

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

An Agent created from the console ships without agent.yaml and without AGENT_CONFIG, so it runs on levels 3 and 4 — setting an environment variable is enough to change the persona, no code change required.

Changing only the persona and model: environment variables

tcb agent update <agentId> \
  -e <envId> \
  --env "CLOUDBASE_ENV_ID=<envId>,CLOUDBASE_APIKEY=<environment API key>,AGENT_MODEL=deepseek-v4-pro,AGENT_SYSTEM=<URL-encoded persona>"

Changes take effect immediately; the code does not need to be redeployed.

Two things to watch out for:

--env replaces the whole set rather than appending to it. The command must include the Agent's existing CLOUDBASE_ENV_ID and CLOUDBASE_APIKEY — both are present by default on console-created Agents. Drop the environment ID and the Agent fails with toKernelAgentConfig: envId is required. Check the current values first:

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

AGENT_SYSTEM must be URL-encoded. The runtime runs decodeURIComponent on it, so raw non-ASCII text is not parsed correctly:

node -e "console.log(encodeURIComponent('You are a customer service agent. Only answer questions about orders and shipping.'))"

Also note that the default model hy3-preview must be enabled for your environment. If it is not, calls return AI_MODEL_NOT_SUPPORTED; setting AGENT_MODEL explicitly resolves it. See Model integration for available models.

Full configuration: agent.yaml

To configure tools, MCP servers, or approval policies, place an agent.yaml in the project root:

name: my-agent
model: deepseek-v4-pro
system: |
  You are a customer service agent for an online store.
  Only answer questions about orders, shipping, and returns; politely decline anything else.
description: E-commerce support Agent

# Tools
tools:
  # Built-in tools (bash / read / write / edit / glob / grep)
  - type: agent_toolset
    default_config:
      enabled: true
      permission_policy:
        type: always_ask       # always_ask requires human approval; always_allow runs directly
    configs:
      - name: bash
        permission_policy:
          type: always_ask

  # Client-side custom tool (executed by the caller, result sent back)
  - type: custom
    name: getClientInfo
    description: Get client-side user info
    input_schema:
      type: object
      properties:
        query:
          type: string
      required: [query]

  # Reference the MCP server declared below
  - type: mcp_toolset
    mcp_server_name: my-mcp

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

Field reference

Field	Required	Description
name	Yes	Agent name
model	Yes	Model ID string, or { id, apiKey, apiBaseUrl, options } to use a model with its own endpoint
system	Yes	System prompt — the Agent's persona and behavioral constraints
description	No	Agent description
tools	No	Tool configuration. Three type values: agent_toolset (built-in tools), custom (client-side tools), mcp_toolset (reference an MCP server)
mcp_servers	No	MCP server declarations, { type: url, name, url }
skills	No	Skill list, { source }
metadata	No	Custom key-value pairs
sessions_collection	No	Database collection used for session storage, defaults to acp_sessions

Built-in tool names: bash, read, write, edit, glob, grep.

permission_policy.type accepts always_ask (human approval before the call) or always_allow (run directly).

Do not mix field names with the OAK SDK

agent.yaml uses snake_case, which is not the same set of names as the camelCase parameters of createAgent() when you call the OAK SDK directly:

agent.yaml	createAgent()
system	systemPrompt
mcp_servers	mcpServers

Unknown fields are ignored silently, which shows up as configuration that "did not take effect" — the persona falls back to the default You are a helpful assistant.. For the SDK style, see OpenAgentKernel.

Welcome messages and opening questions

These are presentation-layer data and are better kept out of the Agent configuration. Store them in a database configuration table and let the front end read and render them, so changes take effect without a redeploy. See OpenAgentKernel — Dynamic welcome message and opening questions.

Related Documentation

• OpenAgentKernel (official SDK)
• ACP Protocol
• Model integration