> ## 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.
# Invoke Harness
> Available only on KeyAuth deployments; waits for completion and returns JSON. Shared OAuth deployments do not expose this endpoint. Overrides apply only to this request, with omitted fields inherited from deployment; `harness_merge` and `harness_enhance` are not supported
`tools` and `skills` append to existing configuration. `mcp_servers` replaces the full list, and an empty list clears MCP for this request. Execution failures can still return HTTP 200; inspect `error`, which is null on success. MCP-only overrides may leave `overwrite` false
Use this endpoint on KeyAuth deployments, with text in `prompt` and user/session identifiers in `run_agent_request`. `harness_name` is echoed in the request and response; sessions still use the `harness_agent` application. Shared OAuth deployments do not expose this endpoint
`harness` applies only to this invocation; omitted fields inherit deployment settings. `tools` appends registered [built-in tools](/productions/api-reference/preview/en/harness-runtime/tools), while `mcp_servers` replaces the remote MCP list
This endpoint runs the agent and saves session events. It can call models, tools, and cloud resources; retries can repeat external actions
The response arrives after completion. Check that `error` is `null`; HTTP `200` or `overwrite` alone does not establish success. On failure, `output` is an empty string
## OpenAPI
````yaml productions/api-reference/openapi/en/harness-runtime.json POST /harness/invoke
openapi: 3.1.0
info:
title: Harness Runtime
version: agentkit-cli 0.54.0 / SDK 0.8.0 / ADK 2.2.0
description: >-
Harness Runtime deployed by AgentKit CLI 0.54.0, verified with VeADK 1.0.8,
AgentKit SDK 0.8.0, and Google ADK 2.2.0; scheduled tasks require separate
enablement
servers:
- url: http://localhost:8000
description: Local server
security:
- {}
- RuntimeBearer: []
tags:
- name: Service and applications
- name: Sessions
- name: Agent execution
- name: Artifacts
- name: Memory
- name: Evaluation · development server
- name: Debugging · development server
- name: Compatibility endpoints
- name: Harness cronjobs
paths:
/harness/invoke:
post:
tags:
- Harness invocation
summary: Invoke Harness
description: >-
Available only on KeyAuth deployments; waits for completion and returns
JSON. Shared OAuth deployments do not expose this endpoint. Overrides
apply only to this request, with omitted fields inherited from
deployment; `harness_merge` and `harness_enhance` are not supported
`tools` and `skills` append to existing configuration. `mcp_servers`
replaces the full list, and an empty list clears MCP for this request.
Execution failures can still return HTTP 200; inspect `error`, which is
null on success. MCP-only overrides may leave `overwrite` false
operationId: harnessRuntimeInvoke
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/InvokeHarnessRequest'
examples:
basic:
value:
prompt: Hello
harness_name: harness
run_agent_request:
user_id: user-001
session_id: session-001
overrides:
value:
prompt: Hello
harness_name: harness
harness:
system_prompt: Answer concisely
tools: web_search
mcp_servers:
- endpoint: https://mcp.example.com/mcp
api_key:
run_agent_request:
user_id: user-001
session_id: session-001
max_llm_calls: 10
required: true
responses:
'200':
description: Invocation result; inspect the error field
content:
application/json:
schema:
$ref: '#/components/schemas/InvokeHarnessResponse'
example:
harness_name: harness
overwrite: false
output: Hello
error: null
'422':
description: Request validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/HTTPValidationError'
components:
schemas:
InvokeHarnessRequest:
properties:
prompt:
type: string
title: Prompt
description: User message for this invocation
harness_name:
type: string
title: Harness Name
description: >-
Harness name echoed in the request and response; sessions use the
fixed harness_agent namespace
harness:
anyOf:
- $ref: '#/components/schemas/HarnessOverrides'
- type: 'null'
description: >-
Per-request overrides; omitted fields inherit the deployed
configuration
run_agent_request:
$ref: '#/components/schemas/HarnessInvocationSession'
description: User, session, and model-call limit for this invocation
type: object
required:
- prompt
- harness_name
- run_agent_request
title: InvokeHarnessRequest
InvokeHarnessResponse:
properties:
harness_name:
type: string
title: Harness Name
description: >-
Harness name echoed in the request and response; sessions use the
fixed harness_agent namespace
overwrite:
type: boolean
title: Overwrite
default: false
description: >-
Whether general Harness overrides were applied; may be false for
MCP-only overrides
output:
type: string
title: Output
description: Text output after completion; empty on failure
error:
anyOf:
- type: string
- type: 'null'
title: Error
description: Invocation error; null on success
type: object
required:
- harness_name
- output
title: InvokeHarnessResponse
HTTPValidationError:
properties:
detail:
items:
$ref: '#/components/schemas/ValidationError'
type: array
title: Detail
description: Error details
type: object
title: HTTPValidationError
HarnessOverrides:
properties:
model_name:
type: string
title: Model Name
default: ''
description: Model name for this invocation
tools:
type: string
title: Tools
default: ''
description: >-
Comma-separated built-in tool names, appended with deduplication; an
empty string does not clear existing tools and invalid names are
skipped. See [Built-in
tools](/productions/api-reference/preview/en/harness-runtime/tools)
for all 13 names, their uses, and prerequisites in the default CLI
0.54.0 deployment
mcp_servers:
items:
$ref: '#/components/schemas/McpServerConfig'
type: array
title: Mcp Servers
description: >-
Remote MCP servers; omission inherits the deployment, a provided
list replaces it, and an empty array disables remote MCP for this
request
skills:
type: string
title: Skills
default: ''
description: >-
Comma-separated Skill Hub slugs, skill-space IDs, or space:skill
references; appended for this request. An empty string does not
clear deployed skills
system_prompt:
type: string
title: System Prompt
default: ''
description: System prompt replacement; an empty string clears the instruction
runtime:
type: string
enum:
- adk
- codex
title: Runtime
default: adk
description: Execution backend for this invocation
registry_space_id:
type: string
title: Registry Space Id
default: ''
description: Agent registry space ID
registry_endpoint:
type: string
title: Registry Endpoint
default: ''
description: Agent registry endpoint
registry_region:
type: string
title: Registry Region
default: ''
description: Agent registry region
registry_top_k:
type: integer
minimum: 1
title: Registry Top K
default: 3
description: >-
Number of registry search results; defaults to 3 and must be at
least 1
max_llm_calls:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Max Llm Calls
description: >-
Model-call limit, at least 1; run_agent_request takes precedence
over harness overrides, followed by the deployed configuration
type: object
title: HarnessOverrides
HarnessInvocationSession:
properties:
user_id:
type: string
title: User Id
description: User ID
session_id:
type: string
title: Session Id
description: Session ID
max_llm_calls:
anyOf:
- type: integer
minimum: 1
- type: 'null'
title: Max Llm Calls
description: >-
Model-call limit, at least 1; run_agent_request takes precedence
over harness overrides, followed by the deployed configuration
type: object
required:
- user_id
- session_id
title: RunAgentRequest
ValidationError:
properties:
loc:
items:
anyOf:
- type: string
- type: integer
type: array
title: Location
description: Location of the invalid field
msg:
type: string
title: Message
description: Validation error message
type:
type: string
title: Error Type
input:
title: Input
ctx:
type: object
title: Context
type: object
required:
- loc
- msg
- type
title: ValidationError
McpServerConfig:
properties:
protocol:
type: string
enum:
- streamable-http
- sse
title: Protocol
default: streamable-http
description: MCP transport; defaults to streamable-http and also supports sse
endpoint:
type: string
title: Endpoint
description: >-
HTTP(S) endpoint without user information, a fragment, or control
characters
api_key:
anyOf:
- type: string
format: password
writeOnly: true
- type: 'null'
title: Api Key
description: >-
Optional Bearer credential for the MCP service; line breaks are
forbidden. This is separate from Runtime access credentials
additionalProperties: false
type: object
required:
- endpoint
title: McpServerConfig
securitySchemes:
RuntimeBearer:
type: http
scheme: bearer
description: >-
Optional locally without a gateway; cloud deployments use the Runtime
API key or user-pool JWT required by that deployment, never the model
API key
````