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

# Trigger a chat run (fire-and-forget)

> Trigger a chat run for the specified session.

The run executes as a background task. Events produced during the
run are published to the message bus and delivered to any active
``GET /sessions/{session_id}/stream`` SSE subscriber. The caller
does **not** receive events from this endpoint's response body.

Accepts the same ``input`` payloads as before:

- ``Msg`` / ``list[Msg]``: new user message(s).
- ``UserConfirmResultEvent`` / ``ExternalExecutionResultEvent``:
  resume a paused tool call (human-in-the-loop).
- ``None``: continue from current state.

Args:
    request (`ChatRequest`):
        JSON body with ``agent_id``, ``session_id``, and ``input``.
    user_id (`str`):
        Injected user id.
    chat_service (`ChatService`):
        Injected application-wide chat service.

Returns:
    `ChatTriggerResponse`:
        Confirms the run was scheduled.



## OpenAPI

````yaml /versions/2.0.2/en/deploy/openapi.json post /chat/
openapi: 3.1.0
info:
  title: AgentScope
  version: 2.0.1
servers: []
security: []
paths:
  /chat/:
    post:
      tags:
        - chat
      summary: Trigger a chat run (fire-and-forget)
      description: |-
        Trigger a chat run for the specified session.

        The run executes as a background task. Events produced during the
        run are published to the message bus and delivered to any active
        ``GET /sessions/{session_id}/stream`` SSE subscriber. The caller
        does **not** receive events from this endpoint's response body.

        Accepts the same ``input`` payloads as before:

        - ``Msg`` / ``list[Msg]``: new user message(s).
        - ``UserConfirmResultEvent`` / ``ExternalExecutionResultEvent``:
          resume a paused tool call (human-in-the-loop).
        - ``None``: continue from current state.

        Args:
            request (`ChatRequest`):
                JSON body with ``agent_id``, ``session_id``, and ``input``.
            user_id (`str`):
                Injected user id.
            chat_service (`ChatService`):
                Injected application-wide chat service.

        Returns:
            `ChatTriggerResponse`:
                Confirms the run was scheduled.
      operationId: chat_chat__post
      parameters:
        - name: x-user-id
          in: header
          required: true
          schema:
            type: string
            description: >-
              Caller's user ID. Temporary header-based identity; will be
              replaced by JWT auth.
            title: X-User-Id
          description: >-
            Caller's user ID. Temporary header-based identity; will be replaced
            by JWT auth.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ChatRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ChatTriggerResponse'
        '404':
          description: Not found
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ChatRequest:
      properties:
        agent_id:
          type: string
          title: Agent Id
          description: Agent ID for the chat endpoint.
        session_id:
          type: string
          title: Session Id
          description: The session to send the message to.
        input:
          anyOf:
            - $ref: '#/components/schemas/Msg'
            - items:
                $ref: '#/components/schemas/Msg'
              type: array
            - $ref: '#/components/schemas/UserConfirmResultEvent'
            - $ref: '#/components/schemas/ExternalExecutionResultEvent'
            - type: 'null'
          title: Input
          description: The input message(s), or agent event, or None.
      type: object
      required:
        - agent_id
        - session_id
        - input
      title: ChatRequest
      description: Request body for the chat endpoint.
    ChatTriggerResponse:
      properties:
        status:
          type: string
          title: Status
          description: Always ``"started"`` when the trigger succeeded.
          default: started
        session_id:
          type: string
          title: Session Id
          description: Echo of the session id the run was started for.
      type: object
      required:
        - session_id
      title: ChatTriggerResponse
      description: |-
        Response body for the fire-and-forget chat trigger.

        Confirms that the chat run was scheduled. Events produced by the
        run arrive separately via the session's SSE stream endpoint.
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
    Msg:
      properties:
        name:
          type: string
          title: Name
        content:
          items:
            anyOf:
              - $ref: '#/components/schemas/TextBlock'
              - $ref: '#/components/schemas/ThinkingBlock'
              - $ref: '#/components/schemas/HintBlock'
              - $ref: '#/components/schemas/ToolCallBlock'
              - $ref: '#/components/schemas/ToolResultBlock'
              - $ref: '#/components/schemas/DataBlock'
          type: array
          title: Content
        role:
          type: string
          enum:
            - user
            - assistant
            - system
          title: Role
        id:
          type: string
          title: Id
        metadata:
          additionalProperties: true
          type: object
          title: Metadata
        created_at:
          type: string
          title: Created At
        finished_at:
          anyOf:
            - type: string
            - type: 'null'
          title: Finished At
        usage:
          anyOf:
            - $ref: '#/components/schemas/Usage'
            - type: 'null'
      type: object
      required:
        - name
        - content
        - role
      title: Msg
      description: |-
        The message class in AgentScope, responsible for information storage
        and transmission among different agents.
    UserConfirmResultEvent:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          title: Created At
        type:
          type: string
          const: USER_CONFIRM_RESULT
          title: Type
          default: USER_CONFIRM_RESULT
        reply_id:
          type: string
          title: Reply Id
        confirm_results:
          items:
            $ref: '#/components/schemas/ConfirmResult'
          type: array
          title: Confirm Results
      type: object
      required:
        - reply_id
        - confirm_results
      title: UserConfirmResultEvent
      description: User confirm result event.
    ExternalExecutionResultEvent:
      properties:
        id:
          type: string
          title: Id
        created_at:
          type: string
          title: Created At
        type:
          type: string
          const: EXTERNAL_EXECUTION_RESULT
          title: Type
          default: EXTERNAL_EXECUTION_RESULT
        reply_id:
          type: string
          title: Reply Id
        execution_results:
          items:
            $ref: '#/components/schemas/ToolResultBlock'
          type: array
          title: Execution Results
      type: object
      required:
        - reply_id
        - execution_results
      title: ExternalExecutionResultEvent
      description: External execution result event.
    ValidationError:
      properties:
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          type: array
          title: Location
        msg:
          type: string
          title: Message
        type:
          type: string
          title: Error Type
        input:
          title: Input
        ctx:
          type: object
          title: Context
      type: object
      required:
        - loc
        - msg
        - type
      title: ValidationError
    TextBlock:
      properties:
        type:
          type: string
          const: text
          title: Type
          default: text
        text:
          type: string
          title: Text
        id:
          type: string
          title: Id
      type: object
      required:
        - text
      title: TextBlock
      description: The text block.
    ThinkingBlock:
      properties:
        type:
          type: string
          const: thinking
          title: Type
          default: thinking
        thinking:
          type: string
          title: Thinking
        id:
          type: string
          title: Id
      additionalProperties: true
      type: object
      required:
        - thinking
      title: ThinkingBlock
      description: |-
        The thinking block.

        Allows extra provider-specific fields (e.g. Anthropic's ``signature``)
        via ``extra="allow"`` so that model implementations can pass
        arbitrary metadata without subclassing.
    HintBlock:
      properties:
        type:
          type: string
          const: hint
          title: Type
          default: hint
        hint:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/DataBlock'
              type: array
          title: Hint
        id:
          type: string
          title: Id
        source:
          anyOf:
            - type: string
            - type: 'null'
          title: Source
      type: object
      required:
        - hint
      title: HintBlock
      description: |-
        A block used to provide instructions or hints to the LLM during the
        reasoning-acting loop. When passed to the LLM API, the hint block is
        converted into a user message.

        The ``hint`` field can be a plain string (text-only) or a list of
        :class:`TextBlock` / :class:`DataBlock` for multimodal content
        (e.g. a background tool result containing both text and an image).
    ToolCallBlock:
      properties:
        type:
          type: string
          const: tool_call
          title: Type
          default: tool_call
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        input:
          type: string
          title: Input
        state:
          $ref: '#/components/schemas/ToolCallState'
          default: pending
        suggested_rules:
          items:
            $ref: '#/components/schemas/PermissionRule'
          type: array
          title: Suggested Rules
      additionalProperties: true
      type: object
      required:
        - id
        - name
        - input
      title: ToolCallBlock
      description: |-
        The tool call block.

        Allows extra provider-specific fields (e.g. the OpenAI Responses API's
        ``call_id``) via ``extra="allow"`` without requiring subclassing.
    ToolResultBlock:
      properties:
        type:
          type: string
          const: tool_result
          title: Type
          default: tool_result
        id:
          type: string
          title: Id
        name:
          type: string
          title: Name
        output:
          anyOf:
            - type: string
            - items:
                anyOf:
                  - $ref: '#/components/schemas/TextBlock'
                  - $ref: '#/components/schemas/DataBlock'
              type: array
          title: Output
        state:
          $ref: '#/components/schemas/ToolResultState'
          default: running
      type: object
      required:
        - id
        - name
        - output
      title: ToolResultBlock
      description: The tool result block.
    DataBlock:
      properties:
        type:
          type: string
          const: data
          title: Type
          default: data
        id:
          type: string
          title: Id
        source:
          anyOf:
            - $ref: '#/components/schemas/Base64Source'
            - $ref: '#/components/schemas/URLSource'
          title: Source
        name:
          anyOf:
            - type: string
            - type: 'null'
          title: Name
      type: object
      required:
        - source
      title: DataBlock
      description: The data block for binary content (images, audio, video, etc.).
    Usage:
      properties:
        input_tokens:
          type: integer
          title: Input Tokens
        output_tokens:
          type: integer
          title: Output Tokens
      type: object
      required:
        - input_tokens
        - output_tokens
      title: Usage
      description: The token usage information of a message.
    ConfirmResult:
      properties:
        confirmed:
          type: boolean
          title: Confirmed
        tool_call:
          $ref: '#/components/schemas/ToolCallBlock'
        rules:
          anyOf:
            - items:
                $ref: '#/components/schemas/PermissionRule'
              type: array
            - type: 'null'
          title: Rules
      type: object
      required:
        - confirmed
        - tool_call
      title: ConfirmResult
      description: Confirm result for a tool call.
    ToolCallState:
      type: string
      enum:
        - pending
        - asking
        - allowed
        - submitted
        - finished
      title: ToolCallState
      description: The state of the tool call.
    PermissionRule:
      properties:
        tool_name:
          type: string
          title: Tool Name
        rule_content:
          anyOf:
            - type: string
            - type: 'null'
          title: Rule Content
        behavior:
          $ref: '#/components/schemas/PermissionBehavior'
        source:
          type: string
          title: Source
      type: object
      required:
        - tool_name
        - rule_content
        - behavior
        - source
      title: PermissionRule
      description: >-
        Permission rule for tool usage.


        A permission rule defines whether a specific tool or tool operation

        should be allowed, denied, or require user confirmation. The

        rule_content field has different semantics depending on the tool_name:


        - For "Bash": rule_content is a substring pattern matched against the
          command Example: rule_content="npm install" matches "npm install express"

        - For "Write"/"Read": rule_content is a glob pattern matched against
        file
          paths Example: rule_content="src/**" matches "src/main.py"

        - For other tools: rule_content is a tool-specific filter pattern
    ToolResultState:
      type: string
      enum:
        - success
        - error
        - interrupted
        - denied
        - running
      title: ToolResultState
      description: The tool result state.
    Base64Source:
      properties:
        type:
          type: string
          const: base64
          title: Type
          default: base64
        data:
          type: string
          title: Data
        media_type:
          type: string
          title: Media Type
      type: object
      required:
        - data
        - media_type
      title: Base64Source
      description: The base64 source.
    URLSource:
      properties:
        type:
          type: string
          const: url
          title: Type
          default: url
        url:
          type: string
          minLength: 1
          format: uri
          title: Url
        media_type:
          type: string
          title: Media Type
      type: object
      required:
        - url
        - media_type
      title: URLSource
      description: The URL source.
    PermissionBehavior:
      type: string
      enum:
        - allow
        - deny
        - ask
        - passthrough
      title: PermissionBehavior
      description: |-
        The behavior of permission.

        Attributes:
            ALLOW: Allow the operation
            DENY: Deny the operation
            ASK: Ask the user for permission
            PASSTHROUGH: Let the permission engine continue with rule matching
                (used by tools to defer decision to the engine)

````