> ## 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

The `harness` command group creates an agent without writing any application code: initialize a `harness.yaml`, set its fields, then deploy it directly as a runtime.

## harness init

Create a harness directory (`harness.yaml` + `.env.example`) for a Harness.

| Flag / Argument | Description | Default |
| - | - | - |
| `[name]` | Harness name (or `.` for the current directory) | None |
| `-y, --yes` | Skip prompts and use defaults | `false` |
| `-f, --force` | Scaffold into a non-empty directory / overwrite `harness.yaml` | `false` |

```bash lines theme={null}
agentkit harness init my-harness
```

`harness.yaml` is the single source of configuration for a code-free agent; `harness deploy` expands it into the runtime's environment variables. In the generated file, common fields are active and each component's optional params are shown commented-out, grouped by backend — set a component's `type`, then uncomment the params under that backend. The complete file looks like this:

```yaml harness.yaml lines theme={null}
# =============================================================================
# AgentKit harness configuration (code-free agent).
#
# `agentkit harness deploy` converts this file into the runtime's environment
# variables: top-level fields and `model` are flattened (model.name -> MODEL_NAME,
# tools -> TOOLS, ...); each component's `type` selects its backend, and the
# component's other params map to the env vars that backend reads (e.g. viking
# `project` -> DATABASE_VIKING_PROJECT). Empty values are skipped, so the server
# falls back to its own defaults.
#
# Configure with `agentkit harness set ...` or by editing this file. For a
# component, uncomment the params under the backend you set as `type`.
# =============================================================================

# Harness / runtime name (also the knowledgebase & long-term-memory index name).
#   env: HARNESS_NAME          flag: --name
harness_name: "my-harness"

# Reasoning model name (Ark auth comes from the runtime's IAM role on deploy).
#   env: MODEL_NAME            flag: --model-name
model:
  name: ""

# Built-in tool names.   env: TOOLS   flag: --tools (comma-separated)
tools: []

# Skill hub names.       env: SKILLS  flag: --skills (comma-separated)
skills: []

# Agent instruction (empty = server default).
#   env: SYSTEM_PROMPT         flag: --system-prompt
system_prompt: ""

# Agent description, used by discovery and generated AgentCards.
#   env: DESCRIPTION           flag: --description
description: ""

# Agent runtime backend: adk (default) | codex.
#   env: RUNTIME               flag: --runtime
runtime: adk

# Per-run defaults. Both can be overridden by `agentkit invoke` flags.
#   env: MAX_LLM_CALLS         flag: --max-llm-calls
# max_llm_calls: 20

# Tool-call behavior.
# structured_tool_calls: false
# include_tools_every_turn: true

# --- A2A registry (optional) ------------------------------------------------
# registry:
#   type: agentkit_a2a
#   space_id: ""
#   top_k: 3
#   endpoint: https://open.volcengineapi.com/
#   region: cn-beijing

# --- Knowledge base ----------------------------------------------------------
#   type -> env: KNOWLEDGEBASE_TYPE   flag: --knowledgebase-type
#   "" disables it. Supported: viking | opensearch | redis
knowledgebase:
  type: ""
  # -- viking --      flags: --knowledgebase-project / --knowledgebase-region
  # project: my-project
  # region: cn-beijing
  # -- opensearch --  flags: --knowledgebase-host / -port / -username / -password / -use-ssl
  # host: 1.2.3.4
  # port: 9200
  # username: admin
  # password: ""
  # use_ssl: true
  # -- redis --       flags: --knowledgebase-host / -port / -username / -password / -db
  # host: 1.2.3.4
  # port: 6379
  # username: default
  # password: ""
  # db: 0

# --- Long-term memory --------------------------------------------------------
#   type -> env: LONG_TERM_MEMORY_TYPE   flag: --long-term-memory-type
#   "" disables it. Supported: viking | opensearch | redis | mem0
long_term_memory:
  type: ""
  # -- viking --      flags: --long-term-memory-project / --long-term-memory-region
  # project: my-project
  # region: cn-beijing
  # -- opensearch --  flags: --long-term-memory-host / -port / -username / -password
  # host: 1.2.3.4
  # port: 9200
  # username: admin
  # password: ""
  # -- redis --       flags: --long-term-memory-host / -port / -password / -db
  # host: 1.2.3.4
  # port: 6379
  # password: ""
  # db: 0
  # -- mem0 --        flags: --long-term-memory-api-key / -api-key-id / -project-id / -base-url
  # api_key: ""
  # api_key_id: ""
  # project_id: ""
  # base_url: https://api.mem0.ai/v1

# --- Short-term memory (session store) ---------------------------------------
#   type -> env: SHORT_TERM_MEMORY_TYPE   flag: --short-term-memory-type
#   local (default) | sqlite | mysql | postgresql
short_term_memory:
  type: local
  # -- mysql --       flags: --short-term-memory-host / -user / -password / -database / -charset
  # host: 1.2.3.4
  # user: root
  # password: ""
  # database: harness
  # charset: utf8
  # -- postgresql --  flags: --short-term-memory-host / -port / -user / -password / -database
  # host: 1.2.3.4
  # port: 5432
  # user: postgres
  # password: ""
  # database: harness

# --- Authentication (optional) -----------------------------------------------
# Omit this block to deploy with the default API-key auth (key_auth). Add it to
# gate the runtime with OAuth2/JWT (custom_jwt): the API gateway then only accepts
# tokens issued by `discovery_url`'s user pool whose audience is one of
# `allowed_ids`. Set up the user pool / client in the Volcengine Identity console.
#   flags: --discovery-url / --allowed-id
# auth:
#   discovery_url: "https://userpool-<id>.userpool.auth.id.cn-beijing.volces.com/.well-known/openid-configuration"
#   allowed_ids: ["<client-id>"]
```

Field reference:

* **`harness_name`**: the harness and runtime name, also used as the knowledge-base and long-term-memory index name (env `HARNESS_NAME`, flag `--name`).
* **`model.name`**: the reasoning model; on deploy its Ark auth comes from the runtime's IAM role, so you don't set it here (env `MODEL_NAME`, flag `--model-name`).
* **`tools`**: built-in tool names (env `TOOLS`, flag `--tools`).
* **`skills`**: skill-hub names (env `SKILLS`, flag `--skills`).
* **`system_prompt`**: the agent instruction; empty uses the server default (env `SYSTEM_PROMPT`, flag `--system-prompt`).
* **`description`**: agent description used for discovery and generated AgentCards (env `DESCRIPTION`, flag `--description`).
* **`runtime`**: the agent runtime backend, `adk` (default) or `codex` (env `RUNTIME`, flag `--runtime`).
* **`max_llm_calls`**: default maximum LLM calls per run; `agentkit invoke --max-llm-calls` can override it for one request.
* **`structured_tool_calls`** / **`include_tools_every_turn`**: control the tool-call format and whether tool definitions are sent on every model turn.
* **`registry`**: optional A2A registry. `space_id` selects a space, `top_k` limits AgentCard retrieval, and `endpoint` plus `region` locate the service.
* **`knowledgebase`**: a knowledge base. An empty `type` disables it; supported backends are `viking`, `opensearch`, `redis` — set `type`, then uncomment that backend's connection params.
* **`long_term_memory`**: long-term memory. An empty `type` disables it; supported backends are `viking`, `opensearch`, `redis`, `mem0`.
* **`short_term_memory`**: the session store. `type` is `local` (default), `sqlite`, `mysql`, or `postgresql`.
* **`auth`** (optional): omit it to use the default API-key auth (`key_auth`); set `discovery_url` and `allowed_ids` to switch to OAuth2/JWT (`custom_jwt`), where the gateway only accepts tokens issued by that user pool whose audience is on the allow-list.

<Note>
  Expansion: `harness deploy` flattens top-level fields and `model` into environment variables (e.g. `model.name` → `MODEL_NAME`) and maps component params to the `DATABASE_<BACKEND>_*` variables that backend reads; empty values are skipped and the server falls back to its defaults. The `.env.example` written by `harness init` contains only optional Volcengine AK/SK placeholders — all agent configuration lives in `harness.yaml`.
</Note>

## harness set

Set fields in `harness.yaml` (partial update; only the flags you pass are changed). Run with no flags to list the current fields. Fields fall into groups: core (model / tools / skills / prompt / runtime), knowledgebase, long-term-memory, short-term-memory, and auth. When configuring a component, set its `--<comp>-type` first, then its connection parameters.

| Flag / Argument | Description | Default |
| - | - | - |
| `--name <name>` | Harness/runtime name | None |
| `--model-name <name>` | Reasoning model name | None |
| `--tools <list>` | Comma-separated built-in tools | None |
| `--skills <list>` | Comma-separated skill hub names | None |
| `--system-prompt <text>` | Agent instruction | None |
| `--description <text>` | Agent description used for discovery and AgentCards. | None |
| `--runtime <backend>` | Agent runtime backend: `adk` \| `codex` | None |
| `--max-llm-calls <n>` | Default maximum LLM calls per run; must be a positive integer. | None |
| `--knowledgebase-type <type>` | knowledgebase backend type (`""` disables it) | None |
| `--knowledgebase-project <value>` | knowledgebase project | None |
| `--knowledgebase-region <value>` | knowledgebase region | None |
| `--knowledgebase-host <value>` | knowledgebase host | None |
| `--knowledgebase-port <value>` | knowledgebase port | None |
| `--knowledgebase-username <value>` | knowledgebase username | None |
| `--knowledgebase-password <value>` | knowledgebase password | None |
| `--knowledgebase-use-ssl` | knowledgebase use\_ssl | `false` |
| `--knowledgebase-cert-path <value>` | knowledgebase cert\_path | None |
| `--knowledgebase-secret-token <value>` | knowledgebase secret\_token | None |
| `--knowledgebase-db <value>` | knowledgebase db | None |
| `--long-term-memory-type <type>` | long\_term\_memory backend type (`""` disables it) | None |
| `--long-term-memory-project <value>` | long\_term\_memory project | None |
| `--long-term-memory-region <value>` | long\_term\_memory region | None |
| `--long-term-memory-host <value>` | long\_term\_memory host | None |
| `--long-term-memory-port <value>` | long\_term\_memory port | None |
| `--long-term-memory-username <value>` | long\_term\_memory username | None |
| `--long-term-memory-password <value>` | long\_term\_memory password | None |
| `--long-term-memory-use-ssl` | long\_term\_memory use\_ssl | `false` |
| `--long-term-memory-cert-path <value>` | long\_term\_memory cert\_path | None |
| `--long-term-memory-secret-token <value>` | long\_term\_memory secret\_token | None |
| `--long-term-memory-db <value>` | long\_term\_memory db | None |
| `--long-term-memory-api-key <value>` | long\_term\_memory api\_key | None |
| `--long-term-memory-api-key-id <value>` | long\_term\_memory api\_key\_id | None |
| `--long-term-memory-project-id <value>` | long\_term\_memory project\_id | None |
| `--long-term-memory-base-url <value>` | long\_term\_memory base\_url | None |
| `--short-term-memory-type <type>` | short\_term\_memory backend type (`""` disables it) | None |
| `--short-term-memory-host <value>` | short\_term\_memory host | None |
| `--short-term-memory-user <value>` | short\_term\_memory user | None |
| `--short-term-memory-password <value>` | short\_term\_memory password | None |
| `--short-term-memory-database <value>` | short\_term\_memory database | None |
| `--short-term-memory-charset <value>` | short\_term\_memory charset | None |
| `--short-term-memory-port <value>` | short\_term\_memory port | None |
| `--discovery-url <url>` | OAuth2/JWT OIDC discovery URL (enables custom\_jwt) | None |
| `--allowed-id <ids>` | Comma-separated allowed client IDs | None |
| `--structured-tool-calls` | Use structured tool calls. | Current config |
| `--no-structured-tool-calls` | Disable structured tool calls. | Current config |
| `--include-tools-every-turn` | Send tool definitions on every model turn. | Current config |
| `--reuse-tool-context` | Reuse tool context instead of resending definitions every turn. | Current config |
| `--registry <uri>` | A2A registry: `default`, `disabled`, `agentkit://...`, or an HTTP(S) URL. | None |
| `--registry-space-id <id>` | AgentKit A2A space ID. | None |
| `--registry-space-name <name>` | AgentKit A2A space name; it must be unique. | None |
| `--registry-top-k <n>` | Maximum AgentCards to retrieve; must be a positive integer. | None |
| `--registry-endpoint <url>` | AgentKit A2A registry endpoint. | Current cloud environment's AgentKit endpoint |
| `--registry-region <region>` | AgentKit A2A registry region. | `cloud.region` |

```bash lines theme={null}
agentkit harness set --name my-harness --model-name doubao-pro --runtime adk

agentkit harness set --registry default --registry-space-name Default --registry-top-k 3
```

<Tip>
  Only the flags you pass are changed. To configure a component, set its `--<comp>-type` first, then supply its connection parameters.
</Tip>

## harness dev

Start the Harness service locally from `harness.yaml` for development and debugging. By default, it listens on `127.0.0.1:8000`. Set a different host explicitly if other devices need to access it.

| Flag | Description | Default |
| - | - | - |
| `-p, --port <port>` | Port to listen on. | `8000` |
| `--host <host>` | Host address to bind. | `127.0.0.1` |
| `--reload` | Restart when the service code changes. | `false` |
| `--python <bin>` | Python interpreter used to start the service. | `python3` |

```bash lines theme={null}
agentkit harness dev --reload --port 8000
```

## harness deploy

Build the harness image and create or update the runtime from `harness.yaml`.

| Flag / Argument | Description | Default |
| - | - | - |
| `-r, --region <region>` | Runtime deploy region | None |
| `-p, --project <name>` | AgentKit project | `default` |
| `--discovery-url <url>` | OIDC discovery URL (enables OAuth2/JWT, overrides `harness.yaml`) | None |
| `--allowed-id <ids>` | Comma-separated allowed client IDs (overrides `harness.yaml`) | None |

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