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

# 流式运行智能体

> 以 text/event-stream 返回事件，每条消息使用 data: 加 JSON 事件；streaming=true 时请求模型的增量流式输出

`streaming` 默认 false，此时仍使用 SSE 传输完整事件。成功流中的 JSON 事件使用 Event 结构；流已开始后的错误以 `data: {"error":"..."}` 发送。使用 `curl -N` 查看实时输出；交互式请求面板不保证逐事件展示

默认需先创建会话；启用 `--auto_create_session` 后可自动创建。`appName` 可在设置 `ADK_DEFAULT_APP_NAME` 时省略

默认先[创建会话](/productions/api-reference/preview/zh/agent-api-server/create-session)，再提交消息。`streaming` 默认为 `false`，此时仍通过 SSE 发送完整事件；设为 `true` 时请求模型增量输出

<Warning>
  运行会写入会话事件，并可能调用模型、工具与外部资源。重试请求可能再次执行外部操作
</Warning>

每个 SSE 消息以 `data:` 开头，后接 JSON，并以空行结束。使用 `curl -N` 持续读取；事件可能只包含状态或制品变更，不一定包含文本，`partial: true` 表示增量内容

```text theme={null}
data: {"content":{"role":"model","parts":[{"text":"Hello"}]},"partial":false,"author":"travel_assistant","invocationId":"invocation-001","id":"event-001","timestamp":1789603200}

data: {"error":"Example execution error"}

```

以上分别展示消息事件与错误事件的格式，不表示每次成功调用都会返回错误。HTTP `200` 仅表示流已开始；客户端还需检查流中的 `error`，并读取到连接结束。交互式请求面板不保证逐事件展示


## OpenAPI

````yaml productions/api-reference/openapi/zh/agent-api-server.json POST /run_sse
openapi: 3.1.0
info:
  title: Agent API Server
  version: google-adk 2.2.0
  description: 基于 Google ADK 2.2.0 的公开 HTTP 接口；/dev 路由仅在启用开发界面的服务中可用
servers:
  - url: http://localhost:8000
    description: 本地服务
security: []
tags:
  - name: 服务与应用
  - name: 会话
  - name: 智能体运行
  - name: 制品
  - name: 记忆
  - name: 评测 · 开发服务
  - name: 调试 · 开发服务
  - name: 兼容接口
paths:
  /run_sse:
    post:
      tags:
        - 智能体运行
      summary: 流式运行智能体
      description: >-
        以 text/event-stream 返回事件，每条消息使用 data: 加 JSON 事件；streaming=true
        时请求模型的增量流式输出


        `streaming` 默认 false，此时仍使用 SSE 传输完整事件。成功流中的 JSON 事件使用 Event 结构；流已开始后的错误以
        `data: {"error":"..."}` 发送。使用 `curl -N` 查看实时输出；交互式请求面板不保证逐事件展示


        默认需先创建会话；启用 `--auto_create_session` 后可自动创建。`appName` 可在设置
        `ADK_DEFAULT_APP_NAME` 时省略
      operationId: agentApiRunSse
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunAgentRequest'
            example:
              appName: travel_assistant
              userId: user-001
              sessionId: session-001
              newMessage:
                role: user
                parts:
                  - text: Plan a day in Beijing
              streaming: true
        required: true
      responses:
        '200':
          description: 请求成功
          content:
            text/event-stream:
              schema:
                type: string
              example: >+
                data:
                {"content":{"role":"model","parts":[{"text":"Hello"}]},"author":"travel_assistant","invocationId":"invocation-001","id":"event-001","timestamp":1789603200}

        '400':
          description: 请求不符合接口要求，或所需服务/依赖未配置
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '404':
          description: 请求的资源不存在
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiError'
        '422':
          description: 请求参数验证失败
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
      x-codeSamples:
        - lang: Shell
          label: cURL
          source: |-
            curl -N -X POST 'http://localhost:8000/run_sse' \
              -H 'Content-Type: application/json' \
              -d '{"appName": "travel_assistant", "userId": "user-001", "sessionId": "session-001", "newMessage": {"role": "user", "parts": [{"text": "Plan a day in Beijing"}]}, "streaming": true}'
components:
  schemas:
    RunAgentRequest:
      properties:
        appName:
          anyOf:
            - type: string
            - type: 'null'
          title: Appname
          description: 应用名称；省略时使用 ADK_DEFAULT_APP_NAME，未配置默认应用则返回 400
        userId:
          type: string
          title: Userid
          description: 用户 ID
        sessionId:
          type: string
          title: Sessionid
          description: 会话 ID
        newMessage:
          anyOf:
            - $ref: '#/components/schemas/Content-Input'
            - type: 'null'
          description: 本轮输入消息；恢复调用时可省略，具体取决于应用支持的调用方式
        streaming:
          type: boolean
          title: Streaming
          default: false
          description: 是否请求模型增量流式输出，默认 false
        stateDelta:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Statedelta
          description: 本次写入的会话状态增量
        functionCallEventId:
          anyOf:
            - type: string
            - type: 'null'
          title: Functioncalleventid
          description: 对应函数调用的事件 ID，用于函数响应相关的流式处理
        invocationId:
          anyOf:
            - type: string
            - type: 'null'
          title: Invocationid
          description: 调用 ID
        customMetadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          title: Custommetadata
          description: 自定义元数据
      type: object
      required:
        - userId
        - sessionId
      title: RunAgentRequest
    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
    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
    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

````