> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpertai.cn/llms.txt
> Use this file to discover all available pages before exploring further.

# 发起运行并等待结果

> 发起一次新运行，在事件流完成后返回聚合的纯文本。当前响应为 `{"role":"ai","content":"..."}`，不是 Run 记录或完整图状态。本接口不是等待已有 run_id；需处理中断及详细进度时使用流式接口。



## OpenAPI

````yaml /api/openapi.sdk.zh-Hans.json post /api/ai/threads/{thread_id}/runs/wait
openapi: 3.0.3
info:
  title: XpertAI SDK HTTP 接口
  version: 1.0.0
  description: >-
    SDK 指南使用的当前 HTTP 接口。使用服务端 API Key，通过 Authorization: Bearer <API_KEY> 或
    x-api-key 鉴权，不依赖 ChatKit。本参考覆盖指南中的案例，不代表 SDK 导出的所有方法都已实现；使用其他字段前请核对部署支持情况。
servers:
  - url: https://api.xpertai.cn
    description: XpertAI API，私有部署请替换为自己的 API 服务地址。
security:
  - ApiKeyBearer: []
  - ApiKeyHeader: []
tags:
  - name: Assistants
  - name: Threads
  - name: Runs
  - name: Contexts
  - name: Store
paths:
  /api/ai/threads/{thread_id}/runs/wait:
    post:
      tags:
        - Runs
      summary: 发起运行并等待结果
      description: >-
        发起一次新运行，在事件流完成后返回聚合的纯文本。当前响应为 `{"role":"ai","content":"..."}`，不是 Run
        记录或完整图状态。本接口不是等待已有 run_id；需处理中断及详细进度时使用流式接口。
      operationId: wait_run
      parameters:
        - name: thread_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunRequest'
            example:
              assistant_id: 22222222-2222-4222-8222-222222222222
              input:
                action: send
                message:
                  input:
                    input: Hello, introduce yourself briefly.
      responses:
        '201':
          description: 请求成功。
          content:
            application/json:
              schema:
                type: object
                properties:
                  role:
                    type: string
                    enum:
                      - ai
                  content:
                    type: string
                required:
                  - role
                  - content
              example:
                role: ai
                content: Hello
        '400':
          description: 请求参数、标识关联或操作状态不正确。
        '401':
          description: 缺少 API Key 或 API Key 无效。
        '403':
          description: 调用方无权访问目标资源。
        '404':
          description: 资源不存在或对调用方不可用。
components:
  schemas:
    RunRequest:
      type: object
      properties:
        assistant_id:
          type: string
          description: 已发布智能体 ID。HTTP 字段为 assistant_id，SDK 则将 assistantId 作为方法参数传入。
        input:
          oneOf:
            - $ref: '#/components/schemas/SendInput'
            - $ref: '#/components/schemas/ResumeInput'
            - $ref: '#/components/schemas/RetryInput'
            - $ref: '#/components/schemas/FollowUpInput'
          discriminator:
            propertyName: action
            mapping:
              send: '#/components/schemas/SendInput'
              retry: '#/components/schemas/RetryInput'
              resume: '#/components/schemas/ResumeInput'
              follow_up: '#/components/schemas/FollowUpInput'
          description: 对话操作对象。示例使用 send；retry、resume 和 follow_up 需要匹配的执行状态与权限。
        context:
          type: object
          additionalProperties: true
          description: 可选运行上下文，仅传入目标部署和智能体支持的字段。
      required:
        - assistant_id
        - input
    SendInput:
      type: object
      properties:
        action:
          type: string
          enum:
            - send
        conversationId:
          type: string
          description: 如填写，必须与 URL 中线程所属对话一致；从线程响应的 metadata.conversation_id 读取。
        message:
          $ref: '#/components/schemas/Message'
        state:
          type: object
          additionalProperties: true
        projectId:
          type: string
        environmentId:
          type: string
        sandboxEnvironmentId:
          type: string
      required:
        - action
        - message
    ResumeInput:
      type: object
      properties:
        action:
          type: string
          enum:
            - resume
        conversationId:
          type: string
          description: 如填写，必须与 URL 中线程所属对话一致；从线程响应的 metadata.conversation_id 读取。
        target:
          $ref: '#/components/schemas/Target'
        decision:
          type: object
          properties:
            type:
              type: string
              enum:
                - confirm
                - reject
            payload: {}
          required:
            - type
        patch:
          type: object
          properties:
            agentKey:
              type: string
            toolCalls:
              type: array
              items: {}
            update: {}
        state:
          type: object
          additionalProperties: true
      required:
        - action
        - target
        - decision
    RetryInput:
      type: object
      properties:
        action:
          type: string
          enum:
            - retry
        conversationId:
          type: string
          description: 如填写，必须与 URL 中线程所属对话一致；从线程响应的 metadata.conversation_id 读取。
        source:
          $ref: '#/components/schemas/Target'
        environmentId:
          type: string
        sandboxEnvironmentId:
          type: string
      required:
        - action
        - source
    FollowUpInput:
      type: object
      properties:
        action:
          type: string
          enum:
            - follow_up
        conversationId:
          type: string
          description: 如填写，必须与 URL 中线程所属对话一致；从线程响应的 metadata.conversation_id 读取。
        mode:
          type: string
          enum:
            - queue
            - steer
        message:
          $ref: '#/components/schemas/Message'
        target:
          $ref: '#/components/schemas/Target'
        state:
          type: object
          additionalProperties: true
      required:
        - action
        - mode
        - message
    Message:
      type: object
      properties:
        clientMessageId:
          type: string
          description: 调用方消息标识，不代表服务端保证幂等。
        input:
          type: object
          properties:
            input:
              type: string
              description: 用户文本。其他输入变量由智能体定义。
            files:
              type: array
              items:
                $ref: '#/components/schemas/AgentFile'
          additionalProperties: true
      required:
        - input
    Target:
      type: object
      properties:
        aiMessageId:
          type: string
        executionId:
          type: string
      description: 使用原执行或中断事件返回的标识，不要编造目标 ID。
    AgentFile:
      type: object
      properties:
        id:
          type: string
          description: FileAsset ID。将返回的文件句柄放入 message.input.files。
        fileId:
          type: string
        storageFileId:
          type: string
          description: 知识库文档关联所需的 StorageFile ID，不能用 FileAsset ID 替代。
        url:
          type: string
        originalName:
          type: string
        size:
          type: integer
        mimeType:
          type: string
        status:
          type: string
        parseStatus:
          type: string
        parseMode:
          type: string
        purpose:
          type: string
      required:
        - id
  securitySchemes:
    ApiKeyBearer:
      type: http
      scheme: bearer
      description: 服务端 API Key，不要暴露到浏览器代码中。
    ApiKeyHeader:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.