Harness Server Deployment

The Harness server is a standalone VeADK agent runtime that you create, configure, and deploy with the veadk harness command line. Once deployed, it runs as an AgentKit Runtime and provides conversation endpoints, session management, and runtime config override capabilities. It suits scenarios where you need to host an agent independently and call it through an HTTP API.

When to use

Scenario	Use case
Standalone deployment	Deploy a VeADK agent as an independent AgentKit Runtime without a Studio-generated project
HTTP API access	Call the agent through HTTP endpoints with per-request config overrides
Config file management	Manage agent configuration in `harness.yaml` and update it through CLI commands

Prerequisites

Python 3.10–3.13 with veadk-python[harness] installed; this extra provides Headroom compression support
Volcengine VOLCENGINE_ACCESS_KEY and VOLCENGINE_SECRET_KEY with permission to build images, access TOS, create Runtimes, and configure IAM roles in the target region
An enabled model or endpoint accessible to the Runtime IAM role, plus separate connection settings and permissions for knowledge bases, databases, and tools

pip install "veadk-python[harness]"

veadk harness deploy uses the Volcengine deployment flow and has no BytePlus options. For no-code deployment on BytePlus, use Harness in the standalone AgentKit CLI. The command groups and configuration files are not interchangeable The generated Dockerfile builds the service from VeADK main by default. To reproduce a released version, set its VEADK_REF to the required tag before building. Commands on this page were checked against VeADK 1.1.13

Command overview

veadk harness provides the following subcommands:

Command	Purpose
`create`	Scaffold a deployable Harness project in the specified directory, including `harness.yaml`, `.env.example`, `Dockerfile`, and other files
`add`	Write agent parameters into `harness.yaml`
`show`	Display the configured parameters in `harness.yaml` and the per-invocation overridable parameters
`deploy`	Convert `harness.yaml` into runtime environment variables and perform an AgentKit cloud build and Runtime creation
`invoke`	Call a deployed Harness server and print the output

create, add, and show operate on local files. deploy uses cloud resources, and invoke calls the deployed service and may consume model usage

Create a project

If the target directory is non-empty, confirmation allows existing project files to be overwritten. Back up required configuration or use a new directory first

veadk harness create my-harness

This command generates the following files in the my-harness directory:

File	Purpose
`harness.yaml`	Agent configuration file, converted to runtime environment variables on deploy
`.env.example`	Volcengine deploy credential template; copy to `.env` and fill in
`.gitignore`	Ignores local credentials and generated deploy metadata
`Dockerfile`	Builds the Harness server image
`README.md`	Project readme

Parameter	Type	Default	Description
`DIR_NAME`	`str`	Required	Output directory relative to the current directory

A non-empty directory triggers overwrite confirmation, so retain required files first. create only generates local files and does not deploy cloud resources Inside the project, copy .env.example to .env and fill in deployment AK/SK values. Exclude .env, harness.json, and configurations containing real secrets from version control. The API key in invocation metadata is also a credential

Configure the agent

Use veadk harness add to write parameters into harness.yaml. Replace your-model-name with an available model or endpoint ID. The knowledge-base example also requires usable VikingDB resources in the selected project and region; omit its three knowledge-base options when not needed:

cd my-harness
veadk harness add \
  --harness-name my-harness \
  --model-name your-model-name \
  --tools web_search,web_fetch \
  --system-prompt "You are a helpful assistant." \
  --knowledgebase-type viking \
  --knowledgebase-project my-project \
  --knowledgebase-region cn-beijing

Configuration parameters

add updates only explicitly supplied fields. Defaults below describe omitted options, not initial server defaults. --path defaults to the current directory, and every subcommand supports --help

Parameter	Type	Default	Description
`--name` / `--harness-name`	`str`	Unchanged	Harness and Runtime name
`--model-name`	`str`	Unchanged	Model or endpoint ID available to the account
`--tools`	`str`	Unchanged	Comma-separated built-in tool names
`--builtin-tools`	`str`	Unchanged	Not persisted by add in this version; use builtin_tools in YAML
`--mcp-router-id`	`str`	Unchanged	Not persisted by add in this version; use mcp_router_id in YAML
`--skills`	`str`	Unchanged	Comma-separated Skill Hub slugs or skill-space references prefixed with space:
`--selected-skills`	`str`	Unchanged	Not persisted by add in this version; use selected_skills in YAML
`--mcp`	`str`	Unchanged	Not persisted by add in this version; use mcp in YAML
`--system-prompt`	`str`	Unchanged	System instruction
`--runtime`	`str`	Unchanged	Runtime backend: adk or codex
`--registry`	`str`	Unchanged	Not persisted by add in this version; use registry in YAML
`--knowledgebase-type`	`str`	Unchanged	Knowledge base backend; an empty string disables it
`--long-term-memory-type`	`str`	Unchanged	Long-term memory backend; an empty string disables it
`--short-term-memory-type`	`str`	Unchanged	Session backend: local, sqlite, mysql, or postgresql
`--max-llm-calls`	`int`	Unchanged	Maximum model calls per run; use a positive integer
`--structured-tool-calls`	`bool`	Unchanged	Enable structured tool calls; edit YAML to false to disable
`--include-tools-every-turn`	`bool`	Unchanged	Send tool definitions every turn; edit YAML to false to disable
`--knowledgebase-project`	`str`	Unchanged	VikingDB project
`--knowledgebase-region`	`str`	Unchanged	VikingDB region
`--knowledgebase-resource-id`	`str`	Unchanged	VikingDB resource ID
`--knowledgebase-host`	`str`	Unchanged	Database host
`--knowledgebase-port`	`str`	Unchanged	Database port, supplied as text
`--knowledgebase-username`	`str`	Unchanged	Redis or OpenSearch username
`--knowledgebase-password`	`str`	Unchanged	Database password written to local configuration
`--knowledgebase-use-ssl`	`str`	Unchanged	OpenSearch SSL; requires the text true or false
`--knowledgebase-cert-path`	`str`	Unchanged	OpenSearch certificate path
`--knowledgebase-secret-token`	`str`	Unchanged	Saved in configuration but not used by the current OpenSearch backend
`--knowledgebase-db`	`str`	Unchanged	Redis database number
`--long-term-memory-project`	`str`	Unchanged	VikingDB project
`--long-term-memory-region`	`str`	Unchanged	VikingDB region
`--long-term-memory-resource-id`	`str`	Unchanged	VikingDB resource ID
`--long-term-memory-host`	`str`	Unchanged	Database host
`--long-term-memory-port`	`str`	Unchanged	Database port, supplied as text
`--long-term-memory-username`	`str`	Unchanged	OpenSearch username; ignored by Redis long-term memory
`--long-term-memory-password`	`str`	Unchanged	Database password written to local configuration
`--long-term-memory-use-ssl`	`str`	Unchanged	OpenSearch SSL; requires the text true or false
`--long-term-memory-cert-path`	`str`	Unchanged	OpenSearch certificate path
`--long-term-memory-secret-token`	`str`	Unchanged	Saved in configuration but not used by the current OpenSearch backend
`--long-term-memory-db`	`str`	Unchanged	Redis database number
`--long-term-memory-api-key`	`str`	Unchanged	Mem0 API key
`--long-term-memory-api-key-id`	`str`	Unchanged	Mem0 API key ID
`--long-term-memory-project-id`	`str`	Unchanged	Mem0 project ID
`--long-term-memory-base-url`	`str`	Unchanged	Mem0 service URL
`--short-term-memory-host`	`str`	Unchanged	Database host
`--short-term-memory-user`	`str`	Unchanged	MySQL or PostgreSQL username
`--short-term-memory-password`	`str`	Unchanged	Database password written to local configuration
`--short-term-memory-database`	`str`	Unchanged	MySQL or PostgreSQL database name
`--short-term-memory-charset`	`str`	Unchanged	MySQL character set
`--short-term-memory-port`	`str`	Unchanged	Database port, supplied as text
`--path`	`str`	`.`	Directory containing harness.yaml

Set the component backend type before its connection settings. Connection options accept text, such as --knowledgebase-use-ssl true; this differs from the boolean switch in the standalone AgentKit CLI. Passwords and API keys are written to local harness.yaml; do not commit files containing real credentials

Although help lists --builtin-tools, --mcp-router-id, --selected-skills, --mcp, and --registry, this version of add does not persist them. Edit YAML directly for structured resources as shown below. OIDC options belong to deploy, not add

A connection field accepted by the CLI is not necessarily used by every backend. Redis usernames work for knowledge bases but are ignored by long-term memory. OpenSearch secret_token is not used by current knowledge-base or memory connections. See Redis memory and OpenSearch knowledge bases

harness.yaml configuration structure

harness.yaml groups model, tool, skill, knowledge-base, and memory settings. Deployment passes them to the Runtime. Each component selects its backend with type and then supplies that backend’s connection settings. The initial session backend is local, and the server defaults to at most 10 model calls per run

harness.yaml

harness_name: my-harness

model:
  name: your-model-name

tools:
  - web_search
  - web_fetch

skills:
  - data-visualization-cloud

system_prompt: "You are a helpful assistant."
runtime: adk

structured_tool_calls: false
include_tools_every_turn: true

max_llm_calls: 10

knowledgebase:
  type: viking
  project: my-project
  region: cn-beijing

long_term_memory:
  type: ""

short_term_memory:
  type: local

Agent fields also accept a harness: wrapper, whose values take precedence over matching top-level fields. Keep deployment harness_name and gateway auth at the top level. add edits top-level fields, so avoid duplicate nested settings. This command does not expand ${VAR} in YAML; do not apply the standalone AgentKit CLI interpolation rules

Structured resource configuration

Beyond the basic fields written by veadk harness add, harness.yaml supports the following structured fields for configuring resources dispatched by the AgentKit control plane. These fields are converted to corresponding JSON environment variables on deploy:

Field	Environment variable	Description
`builtin_tools`	`TOOLS` + tool-level env vars	Structured built-in tool list; each entry has an `id` and optional `config`
`selected_skills`	`SELECTED_SKILLS_JSON`	Structured skill list; each entry has a `source` and a `slug` or `skill_space_id`
`mcp`	`MCP_SERVERS_JSON`	Streamable HTTP MCP server list; each entry has a `name`, `server_url`, and optional `bear_token`
`mcp_router_id`	`MCP_ROUTER_ID`	AgentKit MCP toolset id
`temperature`	`MODEL_AGENT_TEMPERATURE`	Model temperature
`top_p`	`MODEL_AGENT_TOP_P`	Model top_p
`max_llm_calls`	`MAX_LLM_CALLS`	Maximum LLM calls per run

Structured resource configuration example:

harness.yaml

harness:
  model:
    name: your-model-name
  temperature: 0.3
  top_p: 0.9
  max_llm_calls: 8
  builtin_tools:
    - id: run_code
      config:
        tool_id: t-script-1
        region: cn-beijing
    - id: mcp_router
      config:
        url: https://router.example.com/mcp
  selected_skills:
    - source: skillhub
      slug: team/reporting
  mcp:
    - name: db
      server_url: https://db.example.com/mcp
  knowledgebase:
    type: viking
    config:
      index: kb-index
      app_name: kb-index
      project: default
      region: cn-beijing

Execution enhancement configuration

Set harness_enhance in harness.yaml to enable context preparation, tool-result compression, and answer verification. This example uses built-in compression and does not require Headroom

harness.yaml

harness_enhance:
  enabled: true
  components: [invocation_context, compactor, response_verification]
  profile: default
  compression_provider: builtin

Field	Type	Default	Description
`enabled`	`bool`	`false`	Enable enhancement plugins
`components`	`list[str]`	The three components shown above	Select plugin components
`profile`	`str`	`default`	Plugin configuration profile
`compression_provider`	`str`	`builtin`	Compression provider: builtin or headroom

HTTP callers can override these settings for one request through the top-level harness_enhance field, with components supplied as a comma-separated string. Compression can lose details and answer verification does not guarantee factual accuracy. See Harness extension for component behavior and limits

View configuration

veadk harness show

This command prints the parameters configured in harness.yaml, followed by the list of parameters that can be overridden per invocation through veadk harness invoke.

Override knowledge bases, long-term memory, and sampling settings through HTTP. Structured options such as --registry appear in help, but the CLI passes text without parsing JSON objects; use the corresponding HTTP request fields

Parameter	Type	Default	Description
`--path`	`str`	`.`	Directory containing harness.yaml

show prints configuration values without automatically redacting passwords or API keys; remove secrets before sharing output

Deploy

Deployment builds an image and creates or updates cloud resources, which may incur charges. Check the region, Runtime name, model access, and runtime environment settings first. Retain the current configuration before changing a production service. On failure, inspect resources already created before retrying

veadk harness deploy

This command reads harness.yaml, converts it into runtime environment variables, and performs an AgentKit cloud build and Runtime creation. After deployment, the Runtime endpoint, Runtime id, and API key are recorded in harness.json.

Parameter	Type	Default	Description
`--volcengine-access-key`	`str`	`VOLCENGINE_ACCESS_KEY`	Deployment AK; prefer the environment variable
`--volcengine-secret-key`	`str`	`VOLCENGINE_SECRET_KEY`	Deployment SK; prefer the environment variable
`--region`	`str`	`VOLCENGINE_REGION`, then `REGION`, then `cn-beijing`	Deployment region
`--path`	`str`	`.`	Project directory with harness.yaml and Dockerfile
`--discovery-url`	`str`	`auth.discovery_url`	OIDC discovery URL
`--allowed-id`	`str`	`auth.allowed_ids`	Comma-separated allowed client IDs

harness.json is written only when deployment returns an endpoint. API-key mode records the key; OAuth mode records discovery and client settings without storing a user JWT. Default in-memory sessions disappear when the process stops; configure MySQL or PostgreSQL for persistence

Authentication

The default authentication is API key (key_auth). Add an auth section in harness.yaml or use --discovery-url and --allowed-id to enable OAuth2/JWT authentication (custom_jwt):

harness.yaml

auth:
  discovery_url: "https://userpool-<id>.userpool.auth.id.cn-beijing.volces.com/.well-known/openid-configuration"
  allowed_ids: ["<client-id>"]

With OAuth2/JWT authentication, calls must include an Authorization: Bearer <user-pool JWT> header. The CLI does not mint this token.

Invoke the Harness server

veadk harness invoke --name my-harness --message "Describe your capabilities"

--name specifies the Harness name; its URL and API key are read from harness.json. You can also pass --url and --key directly.

Invoke parameters

Parameter	Type	Default	Description
`[MESSAGE]`	`str`	—	Message; supply this or —message
`--name` / `--harness`	`str`	—	Required Harness name used to read harness.json
`--message` / `-m`	`str`	—	Message, taking precedence over the positional argument
`--user-id`	`str`	`cli-user`	Session user ID
`--session-id`	`str`	`cli-session`	Session ID; use different values for separate conversations
`--max-llm-calls`	`int`	—	Override the model-call limit for this invocation
`--url`	`str`	—	Explicit URL, then HARNESS_URL, then harness.json
`--key`	`str`	—	Bearer credential; explicit value, then HARNESS_KEY, then harness.json; also accepts a user JWT
`--path`	`str`	`.`	Directory containing harness.json
`--model-name`	`str`	—	Model or endpoint ID available to the account
`--tools`	`str`	—	Comma-separated built-in tool names
`--builtin-tools`	`str`	—	Does not parse JSON lists; use HTTP builtin_tools
`--mcp-router-id`	`str`	—	MCP toolset ID for this invocation
`--skills`	`str`	—	Comma-separated Skill Hub slugs or skill-space references prefixed with space:
`--selected-skills`	`str`	—	Does not parse JSON lists; use HTTP selected_skills
`--mcp`	`str`	—	Does not parse JSON lists; use HTTP mcp
`--system-prompt`	`str`	—	System instruction
`--runtime`	`str`	—	Runtime backend: adk or codex
`--registry`	`str`	—	Does not parse JSON objects; use HTTP registry

Overrides affect only the current request and do not modify harness.yaml. Use distinct --session-id values for independent conversations; the default cli-user and cli-session reuse the same identifiers After receiving a non-empty reply, verify tools, knowledge, and memory as needed. If CLI output is empty, inspect the HTTP response error field. HTTP 200 alone does not prove successful agent execution

HTTP API

The deployed Harness server exposes the following HTTP endpoints.

Conversation endpoints

Endpoint	Method	Purpose
`/harness/invoke`	`POST`	Invoke the agent and return the full output
`/run_sse`	`POST`	Invoke the agent with SSE streaming

Session and config endpoints

Endpoint	Method	Purpose
`/apps/{app_name}/users/{user_id}/sessions`	`POST`	Create a session, optionally with initial state and events
`/get_agent_config`	`GET` / `POST`	Query the current Harness default configuration

Runtime config overrides

The Harness server supports overriding the deployed agent’s configuration on each request. Overrides are passed in the harness field of the request body and apply only to that call. /harness/invoke request body structure:

Request body

{
  "prompt": "Compile a research report",
  "harness_name": "my-harness",
  "harness": {
    "model_name": "your-model-name",
    "system_prompt": "You are a research assistant.",
    "tools": "web_search,web_fetch",
    "temperature": 0.3
  },
  "harness_merge": false,
  "run_agent_request": {
    "user_id": "user-1",
    "session_id": "session-1"
  }
}

harness_merge behavior

harness_merge controls how the request config is combined with the default config:

`harness_merge`	Behavior
`false` (default)	The `harness` field fully replaces the default config overlay; only fields explicitly set in the request are applied
`true`	The `harness` field is merged with the default config before applying; fields not set in the request retain their default values

Overridable fields

The following fields can be overridden per request through harness:

Field	Type	Description
`model_name`	`str`	Reasoning model name
`tools`	`str`	Built-in tool names, comma-separated
`builtin_tools`	`list`	Structured built-in tool list
`mcp_router_id`	`str`	AgentKit MCP toolset id
`skills`	`str`	Skill names, comma-separated
`selected_skills`	`list`	Structured skill list
`mcp`	`list`	MCP server list
`system_prompt`	`str`	System prompt
`runtime`	`adk` \| `codex`	Runtime backend
`knowledgebase`	`object`	Request-level knowledge base override
`longterm_memory`	`object`	Request-level long-term memory override
`temperature`	`float`	Model temperature
`top_p`	`float`	Model top_p
`max_tokens`	`int`	Maximum output tokens
`presence_penalty`	`float`	Presence penalty
`frequency_penalty`	`float`	Frequency penalty
`penalty`	`float`	Compatibility penalty applied when presence/frequency penalty are not set
`max_llm_calls`	`int`	Maximum LLM calls per run
`registry`	`object`	AgentKit A2A registry override

Request-level knowledge base and long-term memory overrides are resolved from AgentKit control-plane resource ids into runtime configuration. When an id is provided, the Harness server fetches the corresponding resource’s connection info from the AgentKit control plane.

HTTP examples require the deployed endpoint and a real Bearer credential. Read the API key from local harness.json for API-key mode; for OAuth, use a valid JWT issued by the user pool

export HARNESS_URL="https://your-harness-endpoint"
export HARNESS_KEY="your-api-key-or-user-jwt"

Create a session

curl -X POST "$HARNESS_URL/apps/my-harness/users/user-1/sessions" \
  -H "Authorization: Bearer $HARNESS_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sessionId": "session-1", "state": {"key": "value"}}'

The request body can include the following fields:

Field	Type	Description
`id`	`str`	Session id; auto-generated when omitted
`sessionId`	`str`	ADK-compatible session id alias
`state`	`object`	Initial session state
`events`	`list`	Initial session events

Query default configuration

curl "$HARNESS_URL/get_agent_config?app_name=my-harness&user_id=user-1&session_id=session-1" \
  -H "Authorization: Bearer $HARNESS_KEY"

Returns the current Harness default configuration, including model name, runtime backend, and max LLM calls. Supports camelCase query parameters (appName, userId, sessionId) and also accepts a POST request body.

Environment variables

The Harness server configures runtime behavior through environment variables. harness.yaml is automatically converted to the corresponding environment variables on deploy; you can also set them directly in the runtime environment. CLI invocation also accepts HARNESS_URL, HARNESS_KEY, and HARNESS_TIMEOUT, with a 600-second default timeout. The first two supply fallback values for --url and --key; they are not automatically written to deployment configuration

Model and tools

Environment variable	Default	Description
`MODEL_AGENT_NAME`	VeADK default model	Reasoning model name
`MODEL_AGENT_TEMPERATURE`	—	Model temperature
`MODEL_AGENT_TOP_P`	—	Model top_p
`MAX_LLM_CALLS`	`10`	Maximum LLM calls per run
`TOOLS`	—	Built-in tool names, comma-separated
`SKILLS`	—	Skill names, comma-separated
`SYSTEM_PROMPT`	VeADK default instruction	System prompt
`RUNTIME`	`adk`	Runtime backend
`MCP_ROUTER_ID`	—	AgentKit MCP toolset id
`SELECTED_SKILLS_JSON`	—	Structured skill list, JSON format
`MCP_SERVERS_JSON`	—	MCP server list, JSON format
`TOOL_MCP_ROUTER_URL`	—	MCP Router service URL
`TOOL_MCP_ROUTER_API_KEY`	—	MCP Router auth API key
`AGENTKIT_TOOL_ID_SCRIPT`	—	AgentKit Tool id for `run_code`
`AGENTKIT_TOOL_REGION`	—	Shared region for `run_code` and `coding`
`AGENTKIT_TOOL_ID_OPENCODE`	—	AgentKit Tool id for `coding`

Resource configuration

Environment variable	Default	Description
`HARNESS_NAME`	`default`	Harness and Runtime name
`KNOWLEDGEBASE_ID`	—	Knowledge base resource id
`KNOWLEDGEBASE_CONFIG_JSON`	—	Knowledge base backend config, JSON format
`LONG_TERM_MEMORY_ID`	—	Long-term memory resource id
`LONG_TERM_MEMORY_CONFIG_JSON`	—	Long-term memory backend config, JSON format

Session and memory backends

Environment variable	Default	Description
`KNOWLEDGEBASE_TYPE`	—	Knowledge base backend type
`LONG_TERM_MEMORY_TYPE`	—	Long-term memory backend type
`SHORT_TERM_MEMORY_TYPE`	`local`	Short-term session store backend type

The default value of max_llm_calls is 10. When not explicitly set, a single run makes at most 10 LLM calls. Adjust it in harness.yaml or through a request-level override.

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

When to use

Prerequisites

Command overview

Create a project

Configure the agent

Configuration parameters

harness.yaml configuration structure

Structured resource configuration

Execution enhancement configuration

View configuration

Deploy

Authentication

Invoke the Harness server

Invoke parameters

HTTP API

Conversation endpoints

Session and config endpoints

Runtime config overrides

harness_merge behavior

Overridable fields

Create a session

Query default configuration

Environment variables

Model and tools

Resource configuration

Session and memory backends

​When to use

​Prerequisites

​Command overview

​Create a project

​Configure the agent

​Configuration parameters

​harness.yaml configuration structure

​Structured resource configuration

​Execution enhancement configuration

​View configuration

​Deploy

​Authentication

​Invoke the Harness server

​Invoke parameters

​HTTP API

​Conversation endpoints

​Session and config endpoints

​Runtime config overrides

​harness_merge behavior

​Overridable fields

​Create a session

​Query default configuration

​Environment variables

​Model and tools

​Resource configuration

​Session and memory backends

When to use

Prerequisites

Command overview

Create a project

Configure the agent

Configuration parameters

harness.yaml configuration structure

Structured resource configuration

Execution enhancement configuration

View configuration

Deploy

Authentication

Invoke the Harness server

Invoke parameters

HTTP API

Conversation endpoints

Session and config endpoints

Runtime config overrides

harness_merge behavior

Overridable fields

Create a session

Query default configuration

Environment variables

Model and tools

Resource configuration

Session and memory backends