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

> 未提供普通 Harness 覆盖时，通过 SSE 实时返回智能体事件。`streaming` 默认 false，设为 true 时请求模型增量输出；需先创建 harness_agent 下的会话。仅覆盖 `harness.mcp_servers` 时保持原有流式行为

KeyAuth 部署支持普通 `harness` 覆盖，此时服务等待调用完成后返回一个 SSE 事件，不提供逐片段输出，`streaming` 不改变该行为。普通覆盖仅提取 `new_message.parts` 中的文本，`state_delta` 与 `invocation_id` 不应用于此路径

共享 OAuth 部署仅支持 MCP 覆盖，不提供普通模型、工具或提示词覆盖。SSE 中的失败可能以 `data: {"error":"..."}` 返回，HTTP 200 不代表整个调用成功。使用 `curl -N` 观察实时输出

使用 `app_name: "harness_agent"`、`user_id`、`session_id` 和 `new_message` 提交消息。普通调用或仅覆盖 MCP 时，应先创建会话；`streaming: true` 请求模型增量输出

KeyAuth 部署传入普通 `harness` 覆盖时，服务等待执行完成后发送单个 SSE 事件，仅提取 `new_message.parts` 中的文本；不会应用 `state_delta` 或 `invocation_id`。顶层 `max_llm_calls` 仅在这类普通覆盖中生效，并优先于 `harness.max_llm_calls`

<Warning>
  运行会保存会话事件，并可能调用模型与工具。重试可能重复产生外部操作。共享 OAuth 仅允许 MCP 覆盖，完整限制见[服务概述](/productions/api-reference/preview/zh/harness-runtime/overview)
</Warning>

每条 SSE 消息使用 `data: <JSON>` 并以空行分隔。使用 `curl -N` 读取到流结束，同时处理文本、状态或制品事件，以及 `data: {"error":"..."}`；HTTP `200` 不表示执行成功。普通覆盖的成功事件形如：

```text theme={null}
data: {"content":{"parts":[{"text":"Hello"}]},"partial":false}

```


## OpenAPI

````yaml productions/api-reference/openapi/zh/harness-runtime.json POST /run_sse
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:
  /run_sse:
    post:
      tags:
        - 智能体运行
      summary: 流式运行 Harness
      description: >-
        未提供普通 Harness 覆盖时，通过 SSE 实时返回智能体事件。`streaming` 默认 false，设为 true
        时请求模型增量输出；需先创建 harness_agent 下的会话。仅覆盖 `harness.mcp_servers` 时保持原有流式行为


        KeyAuth 部署支持普通 `harness` 覆盖，此时服务等待调用完成后返回一个 SSE 事件，不提供逐片段输出，`streaming`
        不改变该行为。普通覆盖仅提取 `new_message.parts` 中的文本，`state_delta` 与 `invocation_id`
        不应用于此路径


        共享 OAuth 部署仅支持 MCP 覆盖，不提供普通模型、工具或提示词覆盖。SSE 中的失败可能以 `data:
        {"error":"..."}` 返回，HTTP 200 不代表整个调用成功。使用 `curl -N` 观察实时输出
      operationId: harnessRuntimeRunSse
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HarnessRunSseRequest'
            examples:
              basic:
                summary: 基本调用
                value:
                  app_name: harness_agent
                  user_id: user-001
                  session_id: session-001
                  new_message:
                    role: user
                    parts:
                      - text: Hello
                  streaming: true
              mcp:
                summary: 本次请求覆盖 MCP
                value:
                  app_name: harness_agent
                  user_id: user-001
                  session_id: session-001
                  new_message:
                    role: user
                    parts:
                      - text: Hello
                  streaming: true
                  harness:
                    mcp_servers:
                      - protocol: streamable-http
                        endpoint: https://mcp.example.com/mcp
                        api_key: <mcp-service-token>
              general:
                summary: KeyAuth 普通覆盖，单个完成事件
                value:
                  app_name: harness_agent
                  user_id: user-001
                  session_id: session-001
                  new_message:
                    role: user
                    parts:
                      - text: Hello
                  streaming: true
                  harness:
                    system_prompt: Answer concisely
                    tools: web_search
      responses:
        '200':
          description: 请求成功
          content:
            text/event-stream:
              schema:
                type: string
              example: >+
                data:
                {"content":{"role":"model","parts":[{"text":"Hello"}]},"author":"harness_agent","invocationId":"invocation-001","id":"event-001","timestamp":1789603200}

        '400':
          description: 共享 OAuth 请求同时提供 MCP 和其他 Harness 覆盖，或请求不符合接口要求
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      error:
                        type: string
                  - $ref: '#/components/schemas/ApiError'
        '404':
          description: 请求的资源不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '411':
          description: 仅共享 OAuth：必须提供有效 Content-Length
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: CONTENT_LENGTH_REQUIRED
        '413':
          description: 仅共享 OAuth：请求体不得超过 128 KiB
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
              example:
                error: REQUEST_TOO_LARGE
        '422':
          description: 请求参数验证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |-
            curl -N 'http://localhost:8000/run_sse' \
              -H 'Content-Type: application/json' \
              -d '{"app_name": "harness_agent", "user_id": "user-001", "session_id": "session-001", "new_message": {"role": "user", "parts": [{"text": "Hello"}]}, "streaming": true}'
components:
  schemas:
    HarnessRunSseRequest:
      properties:
        app_name:
          anyOf:
            - type: string
            - type: 'null'
          title: Appname
          description: 应用名称，普通调用应明确提供 harness_agent；本接口不使用 ADK_DEFAULT_APP_NAME 作为缺省应用
        user_id:
          type: string
          title: Userid
          description: 用户 ID
        session_id:
          type: string
          title: Sessionid
          description: 会话 ID
        new_message:
          anyOf:
            - $ref: '#/components/schemas/Content-Input'
            - type: 'null'
          description: 本轮输入消息；恢复调用时可省略，具体取决于应用支持的调用方式
        streaming:
          type: boolean
          title: Streaming
          default: false
          description: 是否请求模型增量流式输出，默认 false
        state_delta:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Statedelta
          description: 本次写入的会话状态增量
        function_call_event_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Functioncalleventid
          description: 此字段可被请求模型接受，但所核验 SDK 的 /run_sse 不应用该值
        invocation_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Invocationid
          description: 调用 ID
        custom_metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Custommetadata
          description: 此字段可被请求模型接受，但所核验 SDK 的 /run_sse 不应用该值
        harness:
          $ref: '#/components/schemas/HarnessOverrides'
          description: 仅对本次请求生效的覆盖；未提供的字段继承部署配置；使用覆盖时，顶层请求字段按本页使用 snake_case
        max_llm_calls:
          anyOf:
            - type: integer
              minimum: 1
            - type: 'null'
          description: >-
            仅在 KeyAuth 普通 Harness 覆盖中生效；顶层值优先于
            harness.max_llm_calls，再其次为部署配置。普通调用与仅 MCP 覆盖不应用此字段
      type: object
      required:
        - app_name
        - user_id
        - session_id
      title: HarnessRunSseRequest
    ApiError:
      type: object
      required:
        - detail
      properties:
        detail:
          type: string
          description: 错误详情
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
          description: 错误详情
      type: object
      title: HTTPValidationError
    Content-Input:
      properties:
        parts:
          anyOf:
            - items:
                $ref: '#/components/schemas/Part-Input'
              type: array
            - type: 'null'
          title: Parts
          description: 按顺序排列的消息内容片段
        role:
          anyOf:
            - type: string
            - type: 'null'
          title: Role
          description: 消息角色，例如 user 或 model
      additionalProperties: false
      type: object
      title: Content
    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
    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
    Part-Input:
      properties:
        mediaResolution:
          anyOf:
            - $ref: '#/components/schemas/PartMediaResolution'
            - type: 'null'
        codeExecutionResult:
          anyOf:
            - $ref: '#/components/schemas/CodeExecutionResult'
            - type: 'null'
          description: 代码执行结果
        executableCode:
          anyOf:
            - $ref: '#/components/schemas/ExecutableCode'
            - type: 'null'
          description: 可执行代码
        fileData:
          anyOf:
            - $ref: '#/components/schemas/FileData'
            - type: 'null'
          description: 通过 URI 引用的文件内容
        functionCall:
          anyOf:
            - $ref: '#/components/schemas/FunctionCall'
            - type: 'null'
          description: 模型请求执行的函数调用
        functionResponse:
          anyOf:
            - $ref: '#/components/schemas/FunctionResponse-Input'
            - type: 'null'
          description: 函数执行结果
        inlineData:
          anyOf:
            - $ref: '#/components/schemas/Blob'
            - type: 'null'
          description: 内嵌二进制内容，data 使用 Base64 编码
        text:
          anyOf:
            - type: string
            - type: 'null'
          title: Text
          description: 文本内容
        thought:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Thought
          description: 是否为思考内容
        thoughtSignature:
          anyOf:
            - type: string
              contentEncoding: base64
              contentMediaType: application/octet-stream
            - type: 'null'
          title: Thoughtsignature
          description: 用于后续调用的思考签名
        videoMetadata:
          anyOf:
            - $ref: '#/components/schemas/VideoMetadata'
            - type: 'null'
          description: 视频元数据
        toolCall:
          anyOf:
            - $ref: '#/components/schemas/ToolCall'
            - type: 'null'
        toolResponse:
          anyOf:
            - $ref: '#/components/schemas/ToolResponse'
            - type: 'null'
        partMetadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Partmetadata
      additionalProperties: false
      type: object
      title: Part
    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
    PartMediaResolution:
      properties:
        level:
          anyOf:
            - $ref: '#/components/schemas/PartMediaResolutionLevel'
            - type: 'null'
        numTokens:
          anyOf:
            - type: integer
            - type: 'null'
          title: Numtokens
      additionalProperties: false
      type: object
      title: PartMediaResolution
    CodeExecutionResult:
      properties:
        outcome:
          anyOf:
            - $ref: '#/components/schemas/Outcome'
            - type: 'null'
        output:
          anyOf:
            - type: string
            - type: 'null'
          title: Output
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: 标识符
      additionalProperties: false
      type: object
      title: CodeExecutionResult
    ExecutableCode:
      properties:
        code:
          anyOf:
            - type: string
            - type: 'null'
          title: Code
        language:
          anyOf:
            - $ref: '#/components/schemas/Language'
            - type: 'null'
          description: 应用定义语言
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: 标识符
      additionalProperties: false
      type: object
      title: ExecutableCode
    FileData:
      properties:
        displayName:
          anyOf:
            - type: string
            - type: 'null'
          title: Displayname
        fileUri:
          anyOf:
            - type: string
            - type: 'null'
          title: Fileuri
          description: 文件 URI
        mimeType:
          anyOf:
            - type: string
            - type: 'null'
          title: Mimetype
          description: 内容的 MIME 类型
      additionalProperties: false
      type: object
      title: FileData
    FunctionCall:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: 标识符
        args:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Args
          description: 函数参数对象
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: 名称
        partialArgs:
          anyOf:
            - items:
                $ref: '#/components/schemas/PartialArg'
              type: array
            - type: 'null'
          title: Partialargs
        willContinue:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Willcontinue
      additionalProperties: false
      type: object
      title: FunctionCall
    FunctionResponse-Input:
      properties:
        willContinue:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Willcontinue
        scheduling:
          anyOf:
            - $ref: '#/components/schemas/FunctionResponseScheduling'
            - type: 'null'
        parts:
          anyOf:
            - items:
                $ref: '#/components/schemas/FunctionResponsePart'
              type: array
            - type: 'null'
          title: Parts
          description: 按顺序排列的消息内容片段
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: 标识符
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
          description: 名称
        response:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Response
          description: 响应内容
      additionalProperties: false
      type: object
      title: FunctionResponse
    Blob:
      properties:
        data:
          anyOf:
            - type: string
              contentEncoding: base64
              contentMediaType: application/octet-stream
            - type: 'null'
          title: Data
        displayName:
          anyOf:
            - type: string
            - type: 'null'
          title: Displayname
        mimeType:
          anyOf:
            - type: string
            - type: 'null'
          title: Mimetype
          description: 内容的 MIME 类型
      additionalProperties: false
      type: object
      title: Blob
    VideoMetadata:
      properties:
        endOffset:
          anyOf:
            - type: string
            - type: 'null'
          title: Endoffset
        fps:
          anyOf:
            - type: number
            - type: 'null'
          title: Fps
        startOffset:
          anyOf:
            - type: string
            - type: 'null'
          title: Startoffset
      additionalProperties: false
      type: object
      title: VideoMetadata
    ToolCall:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: 标识符
        toolType:
          anyOf:
            - $ref: '#/components/schemas/ToolType'
            - type: 'null'
        args:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Args
          description: 函数参数对象
      additionalProperties: false
      type: object
      title: ToolCall
    ToolResponse:
      properties:
        id:
          anyOf:
            - type: string
            - type: 'null'
          title: Id
          description: 标识符
        toolType:
          anyOf:
            - $ref: '#/components/schemas/ToolType'
            - type: 'null'
        response:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Response
          description: 响应内容
      additionalProperties: false
      type: object
      title: ToolResponse
    PartMediaResolutionLevel:
      type: string
      enum:
        - MEDIA_RESOLUTION_UNSPECIFIED
        - MEDIA_RESOLUTION_LOW
        - MEDIA_RESOLUTION_MEDIUM
        - MEDIA_RESOLUTION_HIGH
        - MEDIA_RESOLUTION_ULTRA_HIGH
      title: PartMediaResolutionLevel
    Outcome:
      type: string
      enum:
        - OUTCOME_UNSPECIFIED
        - OUTCOME_OK
        - OUTCOME_FAILED
        - OUTCOME_DEADLINE_EXCEEDED
      title: Outcome
    Language:
      type: string
      enum:
        - LANGUAGE_UNSPECIFIED
        - PYTHON
      title: Language
    PartialArg:
      properties:
        boolValue:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Boolvalue
        jsonPath:
          anyOf:
            - type: string
            - type: 'null'
          title: Jsonpath
        nullValue:
          anyOf:
            - type: string
              const: NULL_VALUE
            - type: 'null'
          title: Nullvalue
        numberValue:
          anyOf:
            - type: number
            - type: 'null'
          title: Numbervalue
        stringValue:
          anyOf:
            - type: string
            - type: 'null'
          title: Stringvalue
        willContinue:
          anyOf:
            - type: boolean
            - type: 'null'
          title: Willcontinue
      additionalProperties: false
      type: object
      title: PartialArg
    FunctionResponseScheduling:
      type: string
      enum:
        - SCHEDULING_UNSPECIFIED
        - SILENT
        - WHEN_IDLE
        - INTERRUPT
      title: FunctionResponseScheduling
    FunctionResponsePart:
      properties:
        inlineData:
          anyOf:
            - $ref: '#/components/schemas/FunctionResponseBlob'
            - type: 'null'
          description: 内嵌二进制内容，data 使用 Base64 编码
        fileData:
          anyOf:
            - $ref: '#/components/schemas/FunctionResponseFileData'
            - type: 'null'
          description: 通过 URI 引用的文件内容
      additionalProperties: false
      type: object
      title: FunctionResponsePart
    ToolType:
      type: string
      enum:
        - TOOL_TYPE_UNSPECIFIED
        - GOOGLE_SEARCH_WEB
        - GOOGLE_SEARCH_IMAGE
        - URL_CONTEXT
        - GOOGLE_MAPS
        - FILE_SEARCH
      title: ToolType
    FunctionResponseBlob:
      properties:
        mimeType:
          anyOf:
            - type: string
            - type: 'null'
          title: Mimetype
          description: 内容的 MIME 类型
        data:
          anyOf:
            - type: string
              contentEncoding: base64
              contentMediaType: application/octet-stream
            - type: 'null'
          title: Data
        displayName:
          anyOf:
            - type: string
            - type: 'null'
          title: Displayname
      additionalProperties: false
      type: object
      title: FunctionResponseBlob
    FunctionResponseFileData:
      properties:
        fileUri:
          anyOf:
            - type: string
            - type: 'null'
          title: Fileuri
          description: 文件 URI
        mimeType:
          anyOf:
            - type: string
            - type: 'null'
          title: Mimetype
          description: 内容的 MIME 类型
        displayName:
          anyOf:
            - type: string
            - type: 'null'
          title: Displayname
      additionalProperties: false
      type: object
      title: FunctionResponseFileData
  securitySchemes:
    RuntimeBearer:
      type: http
      scheme: bearer
      description: 本地未配置网关时可不提供；云部署使用 Runtime API Key 或部署要求的用户池 JWT，不能使用模型 API Key

````