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

> 仅用于 KeyAuth 部署，等待调用完成后返回 JSON；共享 OAuth 部署不提供此接口。覆盖只对本次请求生效，未提供的字段继承部署配置，不支持 `harness_merge` 或 `harness_enhance`

`tools` 与 `skills` 追加到已有配置；`mcp_servers` 按整个列表替换，空数组清空本次 MCP。运行失败仍可能返回 HTTP 200，应检查响应 `error`；成功时 `error` 为 null。仅覆盖 MCP 时 `overwrite` 可能为 false

适用于 KeyAuth 部署，使用 `prompt` 提供文本，通过 `run_agent_request` 指定用户和会话。`harness_name` 是请求和响应中的名称，会话仍使用 `harness_agent` 应用；共享 OAuth 部署不提供此接口

`harness` 只影响本次调用，字段省略时继承部署配置。`tools` 追加已注册的[内置工具](/productions/api-reference/preview/zh/harness-runtime/tools)，`mcp_servers` 替换远程 MCP 列表

<Warning>
  本接口会运行智能体并保存会话事件，可能调用模型、工具和云资源。重试可能再次执行外部操作
</Warning>

响应在完成后一次性返回。检查 `error` 是否为 `null`，不要仅凭 HTTP `200` 或 `overwrite` 判断成功；失败时 `output` 为空字符串


## OpenAPI

````yaml productions/api-reference/openapi/zh/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: >-
    AgentKit CLI 0.54.0 部署的 Harness Runtime，基于 VeADK 1.0.8、AgentKit SDK 0.8.0 与
    Google ADK 2.2.0 核验；定时任务另需启用配置
servers:
  - url: http://localhost:8000
    description: 本地服务
security:
  - {}
  - RuntimeBearer: []
tags:
  - name: 服务与应用
  - name: 会话
  - name: 智能体运行
  - name: 制品
  - name: 记忆
  - name: 评测 · 开发服务
  - name: 调试 · 开发服务
  - name: 兼容接口
  - name: Harness 定时任务
paths:
  /harness/invoke:
    post:
      tags:
        - Harness 调用
      summary: 调用 Harness
      description: >-
        仅用于 KeyAuth 部署，等待调用完成后返回 JSON；共享 OAuth
        部署不提供此接口。覆盖只对本次请求生效，未提供的字段继承部署配置，不支持 `harness_merge` 或 `harness_enhance`


        `tools` 与 `skills` 追加到已有配置；`mcp_servers` 按整个列表替换，空数组清空本次 MCP。运行失败仍可能返回
        HTTP 200，应检查响应 `error`；成功时 `error` 为 null。仅覆盖 MCP 时 `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: <mcp-service-token>
                  run_agent_request:
                    user_id: user-001
                    session_id: session-001
                    max_llm_calls: 10
        required: true
      responses:
        '200':
          description: 调用结果，需检查 error 字段
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvokeHarnessResponse'
              example:
                harness_name: harness
                overwrite: false
                output: Hello
                error: null
        '422':
          description: 请求字段验证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    InvokeHarnessRequest:
      properties:
        prompt:
          type: string
          title: Prompt
          description: 本次调用的用户消息
        harness_name:
          type: string
          title: Harness Name
          description: 本次请求与响应中的 Harness 名称；会话使用固定应用命名空间 harness_agent
        harness:
          anyOf:
            - $ref: '#/components/schemas/HarnessOverrides'
            - type: 'null'
          description: 仅对本次请求生效的覆盖；未提供的字段继承部署配置
        run_agent_request:
          $ref: '#/components/schemas/HarnessInvocationSession'
          description: 本次调用的用户、会话和模型调用次数限制
      type: object
      required:
        - prompt
        - harness_name
        - run_agent_request
      title: InvokeHarnessRequest
    InvokeHarnessResponse:
      properties:
        harness_name:
          type: string
          title: Harness Name
          description: 本次请求与响应中的 Harness 名称；会话使用固定应用命名空间 harness_agent
        overwrite:
          type: boolean
          title: Overwrite
          default: false
          description: 是否应用普通 Harness 覆盖；仅覆盖 MCP 时可能为 false
        output:
          type: string
          title: Output
          description: 调用完成后的文本输出；失败时为空字符串
        error:
          anyOf:
            - type: string
            - type: 'null'
          title: Error
          description: 调用错误说明；成功时为 null
      type: object
      required:
        - harness_name
        - output
      title: InvokeHarnessResponse
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
          description: 错误详情
      type: object
      title: HTTPValidationError
    HarnessOverrides:
      properties:
        model_name:
          type: string
          title: Model Name
          default: ''
          description: 本次调用使用的模型名称
        tools:
          type: string
          title: Tools
          default: ''
          description: >-
            逗号分隔的内置工具名称，追加并去重；空字符串不清空已有工具，无效名称被跳过；CLI 0.54.0 默认部署支持的 13
            个名称、用途与依赖见[内置工具](/productions/api-reference/preview/zh/harness-runtime/tools)
        mcp_servers:
          items:
            $ref: '#/components/schemas/McpServerConfig'
          type: array
          title: Mcp Servers
          description: 远程 MCP 服务列表；省略时继承部署配置，提供时整体替换，空数组禁用本次调用的远程 MCP
        skills:
          type: string
          title: Skills
          default: ''
          description: 逗号分隔的 Skill Hub slug、技能空间 ID 或空间:技能引用；追加到本次调用，空字符串不清空已部署技能
        system_prompt:
          type: string
          title: System Prompt
          default: ''
          description: 本次请求替换的系统提示词，空字符串会清空提示词
        runtime:
          type: string
          enum:
            - adk
            - codex
          title: Runtime
          default: adk
          description: 本次调用使用的执行后端
        registry_space_id:
          type: string
          title: Registry Space Id
          default: ''
          description: 智能体注册中心空间 ID
        registry_endpoint:
          type: string
          title: Registry Endpoint
          default: ''
          description: 智能体注册中心地址
        registry_region:
          type: string
          title: Registry Region
          default: ''
          description: 智能体注册中心区域
        registry_top_k:
          type: integer
          minimum: 1
          title: Registry Top K
          default: 3
          description: 注册中心检索返回数量，默认 3，至少为 1
        max_llm_calls:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Llm Calls
          description: 模型调用次数上限，至少为 1；优先采用 run_agent_request 中的值，其次为 harness 覆盖，再其次为部署配置
      type: object
      title: HarnessOverrides
    HarnessInvocationSession:
      properties:
        user_id:
          type: string
          title: User Id
          description: 用户 ID
        session_id:
          type: string
          title: Session Id
          description: 会话 ID
        max_llm_calls:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          title: Max Llm Calls
          description: 模型调用次数上限，至少为 1；优先采用 run_agent_request 中的值，其次为 harness 覆盖，再其次为部署配置
      type: object
      required:
        - user_id
        - session_id
      title: RunAgentRequest
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
          description: 出错字段的位置
        msg:
          type: string
          title: Message
          description: 验证错误说明
        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 传输协议，默认 streamable-http，也支持 sse
        endpoint:
          type: string
          title: Endpoint
          description: HTTP(S) 服务地址，不允许用户名密码、片段标识或控制字符
        api_key:
          anyOf:
            - type: string
              format: password
              writeOnly: true
            - type: 'null'
          title: Api Key
          description: 发送给 MCP 服务的 Bearer 凭证，可省略；不允许换行，不是 Runtime 访问凭证
      additionalProperties: false
      type: object
      required:
        - endpoint
      title: McpServerConfig
  securitySchemes:
    RuntimeBearer:
      type: http
      scheme: bearer
      description: 本地未配置网关时可不提供；云部署使用 Runtime API Key 或部署要求的用户池 JWT，不能使用模型 API Key

````