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

# Create a turn in a session

> Start or continue a turn within a session. Responds with a Server-Sent Events stream.
Use `previous_turn_id` to chain to the session's last turn (defaults to `auto`).



## OpenAPI

````yaml /gateway-agent-harness-openapi.json post /v1/agents/sessions/{sessionId}/turns
openapi: 3.1.0
info:
  title: TrueFoundry Agent Harness
  description: Stateful agent execution API.
  version: 0.1.0
servers:
  - url: '{scheme}://{gatewayBaseURL}/{tenantName}'
    variables:
      scheme:
        default: https
        enum:
          - http
          - https
      gatewayBaseURL:
        default: gateway.truefoundry.ai
        description: Gateway host. Override for self-hosted deployments.
      tenantName:
        default: truefoundry
        description: Tenant identifier
    description: Gateway base URL (per-tenant)
security:
  - AuthorizationBearer: []
paths:
  /v1/agents/sessions/{sessionId}/turns:
    post:
      tags:
        - Agent Harness
      summary: Create a turn in a session
      description: >-
        Start or continue a turn within a session. Responds with a Server-Sent
        Events stream.

        Use `previous_turn_id` to chain to the session's last turn (defaults to
        `auto`).
      parameters:
        - schema:
            type: string
            minLength: 1
            description: Session identifier (<ulid>.<zone>).
            example: 01arz3ndektsv4rrffq69g5fav.g
          required: true
          name: sessionId
          in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTurnRequest'
      responses:
        '200':
          description: Server-Sent Events stream of turn events.
          content:
            text/event-stream:
              schema:
                $ref: '#/components/schemas/TurnStreamingEvent'
        '400':
          description: Bad request — validation failure or Redis store unavailable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
        '403':
          description: Forbidden — only the session creator can add turns.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
        '404':
          description: Prior turn not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
        '412':
          description: >-
            Can be one of:

            - Requested action cannot be performed on session because it is no
            longer usable

            -Sandbox requested but not available
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RequestErrorResponse'
components:
  schemas:
    CreateTurnRequest:
      type: object
      properties:
        input:
          type: array
          items:
            $ref: '#/components/schemas/TurnInputItem'
        previous_turn_id:
          $ref: '#/components/schemas/PreviousTurnIdInput'
    TurnStreamingEvent:
      oneOf:
        - $ref: '#/components/schemas/ModelMessageEvent'
        - $ref: '#/components/schemas/ModelMessageDeltaEvent'
        - $ref: '#/components/schemas/ToolResponseEvent'
        - $ref: '#/components/schemas/ThreadCreatedEvent'
        - $ref: '#/components/schemas/ThreadDoneEvent'
        - $ref: '#/components/schemas/MCPAuthRequiredEvent'
        - $ref: '#/components/schemas/MCPInitializeEvent'
        - $ref: '#/components/schemas/SandboxCreatedEvent'
        - $ref: '#/components/schemas/ToolApprovalRequiredEvent'
        - $ref: '#/components/schemas/ToolResponseRequiredEvent'
        - $ref: '#/components/schemas/TurnCreatedEvent'
        - $ref: '#/components/schemas/TurnDoneEvent'
      discriminator:
        propertyName: type
        mapping:
          model.message:
            $ref: '#/components/schemas/ModelMessageEvent'
          model.message.delta:
            $ref: '#/components/schemas/ModelMessageDeltaEvent'
          tool.response:
            $ref: '#/components/schemas/ToolResponseEvent'
          thread.created:
            $ref: '#/components/schemas/ThreadCreatedEvent'
          thread.done:
            $ref: '#/components/schemas/ThreadDoneEvent'
          mcp.auth_required:
            $ref: '#/components/schemas/MCPAuthRequiredEvent'
          mcp.initialize:
            $ref: '#/components/schemas/MCPInitializeEvent'
          sandbox.created:
            $ref: '#/components/schemas/SandboxCreatedEvent'
          tool.approval_required:
            $ref: '#/components/schemas/ToolApprovalRequiredEvent'
          tool.response_required:
            $ref: '#/components/schemas/ToolResponseRequiredEvent'
          turn.created:
            $ref: '#/components/schemas/TurnCreatedEvent'
          turn.done:
            $ref: '#/components/schemas/TurnDoneEvent'
    RequestErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            type:
              type: string
            code:
              type:
                - string
                - 'null'
            param:
              type:
                - string
                - 'null'
          required:
            - message
      required:
        - error
    TurnInputItem:
      oneOf:
        - $ref: '#/components/schemas/UserMessage'
        - $ref: '#/components/schemas/UserToolApprovalEvent'
        - $ref: '#/components/schemas/UserToolResponseEvent'
      discriminator:
        propertyName: type
        mapping:
          user.message:
            $ref: '#/components/schemas/UserMessage'
          user.tool_approval:
            $ref: '#/components/schemas/UserToolApprovalEvent'
          user.tool_response:
            $ref: '#/components/schemas/UserToolResponseEvent'
    PreviousTurnIdInput:
      anyOf:
        - type: string
          enum:
            - auto
        - type: string
          minLength: 1
        - type: 'null'
      default: auto
      description: >-
        Defaults to 'auto' (chain to session last turn). Use 'null' for the
        session's first turn.
    ModelMessageEvent:
      type: object
      properties:
        content:
          anyOf:
            - type: string
            - type: array
              items:
                anyOf:
                  - $ref: '#/components/schemas/ChatCompletionContentPartText'
                  - $ref: '#/components/schemas/ChatCompletionContentPartRefusal'
            - type: 'null'
        name:
          type: string
        refusal:
          type:
            - string
            - 'null'
        reasoning_content:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCall'
        type:
          type: string
          enum:
            - model.message
        id:
          type: string
          description: Unique identifier for the event
        thread_id:
          type: string
        finish_reason:
          $ref: '#/components/schemas/FinishReason'
        created_at:
          type: string
        usage:
          $ref: '#/components/schemas/ModelMessageUsage'
      required:
        - type
        - id
        - thread_id
        - created_at
    ModelMessageDeltaEvent:
      type: object
      properties:
        content:
          type:
            - string
            - 'null'
        refusal:
          type:
            - string
            - 'null'
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ExtendedChunkDeltaToolCall'
        reasoning_content:
          type: string
        type:
          type: string
          enum:
            - model.message.delta
        id:
          type: string
          description: Unique identifier for the event
        thread_id:
          type: string
        created_at:
          type: string
        finish_reason:
          $ref: '#/components/schemas/FinishReason'
        usage:
          $ref: '#/components/schemas/ModelMessageUsage'
      required:
        - type
        - id
        - thread_id
    ToolResponseEvent:
      type: object
      properties:
        tool_call_id:
          type: string
        content:
          type: string
        type:
          type: string
          enum:
            - tool.response
        id:
          type: string
          description: Unique identifier for the event
        thread_id:
          type: string
        created_at:
          type: string
      required:
        - tool_call_id
        - content
        - type
        - id
        - thread_id
        - created_at
    ThreadCreatedEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - thread.created
        id:
          type: string
          description: Unique identifier for the event
        agent_info:
          $ref: '#/components/schemas/AgentInfo'
        created_at:
          type: string
        parent:
          $ref: '#/components/schemas/AgentParent'
        thread_id:
          type: string
        title:
          type: string
      required:
        - type
        - id
        - agent_info
        - created_at
        - parent
        - thread_id
        - title
    ThreadDoneEvent:
      allOf:
        - $ref: '#/components/schemas/BaseThreadDoneEvent'
        - type: object
          properties:
            type:
              type: string
              enum:
                - thread.done
            id:
              type: string
              description: Unique identifier for the event
            created_at:
              type: string
            state:
              $ref: '#/components/schemas/ThreadState'
          required:
            - type
            - id
            - created_at
            - state
    MCPAuthRequiredEvent:
      allOf:
        - $ref: '#/components/schemas/BaseMCPAuthRequiredEvent'
        - type: object
          properties:
            type:
              type: string
              enum:
                - mcp.auth_required
            mcp_servers:
              type: array
              items:
                $ref: '#/components/schemas/MCPServerAuthInfo'
          required:
            - type
            - mcp_servers
    MCPInitializeEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - mcp.initialize
        id:
          type: string
          description: Unique identifier for the event
        created_at:
          type: string
        thread_id:
          type: string
        mcp_servers:
          type: array
          items:
            $ref: '#/components/schemas/MCPServerInitInfo'
      required:
        - type
        - id
        - created_at
        - thread_id
        - mcp_servers
    SandboxCreatedEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - sandbox.created
        id:
          type: string
          description: Unique identifier for the event
        created_at:
          type: string
        sandbox_id:
          type: string
        thread_id:
          type:
            - string
            - 'null'
      required:
        - type
        - id
        - created_at
        - sandbox_id
        - thread_id
    ToolApprovalRequiredEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - tool.approval_required
        id:
          type: string
          description: Unique identifier for the event
        created_at:
          type: string
        thread_id:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCallRef'
      required:
        - type
        - id
        - created_at
        - thread_id
        - tool_calls
    ToolResponseRequiredEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - tool.response_required
        id:
          type: string
          description: Unique identifier for the event
        created_at:
          type: string
        thread_id:
          type: string
        tool_calls:
          type: array
          items:
            $ref: '#/components/schemas/ToolCallRef'
      required:
        - type
        - id
        - created_at
        - thread_id
        - tool_calls
    TurnCreatedEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - turn.created
        id:
          type: string
          description: Unique identifier for the event
        turn_id:
          type: string
        previous_turn_id:
          type:
            - string
            - 'null'
        state:
          $ref: '#/components/schemas/TurnStateRunning'
        created_by:
          $ref: '#/components/schemas/Subject'
        created_at:
          type: string
        thread_id:
          type:
            - string
            - 'null'
      required:
        - type
        - id
        - turn_id
        - previous_turn_id
        - state
        - created_by
        - created_at
        - thread_id
    TurnDoneEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - turn.done
        id:
          type: string
          description: Unique identifier for the event
        state:
          oneOf:
            - $ref: '#/components/schemas/TurnStateDone'
            - $ref: '#/components/schemas/TurnStateCancelled'
            - $ref: '#/components/schemas/TurnStateError'
          discriminator:
            propertyName: status
            mapping:
              done:
                $ref: '#/components/schemas/TurnStateDone'
              cancelled:
                $ref: '#/components/schemas/TurnStateCancelled'
              error:
                $ref: '#/components/schemas/TurnStateError'
        created_at:
          type: string
        thread_id:
          type:
            - string
            - 'null'
      required:
        - type
        - id
        - state
        - created_at
        - thread_id
    UserMessage:
      type: object
      properties:
        type:
          type: string
          enum:
            - user.message
        content:
          anyOf:
            - type: string
            - type: array
              items:
                $ref: '#/components/schemas/UserMessageContentItem'
      required:
        - type
        - content
    UserToolApprovalEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - user.tool_approval
        thread_id:
          type: string
          minLength: 1
        tool_call_id:
          type: string
          minLength: 1
        approval:
          $ref: '#/components/schemas/ApprovalDecision'
      required:
        - type
        - thread_id
        - tool_call_id
        - approval
    UserToolResponseEvent:
      type: object
      properties:
        type:
          type: string
          enum:
            - user.tool_response
        thread_id:
          type: string
          minLength: 1
        tool_call_id:
          type: string
          minLength: 1
        content:
          type: string
          minLength: 1
      required:
        - type
        - thread_id
        - tool_call_id
        - content
    ChatCompletionContentPartText:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
      required:
        - type
        - text
    ChatCompletionContentPartRefusal:
      type: object
      properties:
        type:
          type: string
          enum:
            - refusal
        refusal:
          type: string
      required:
        - type
        - refusal
    ToolCall:
      allOf:
        - $ref: '#/components/schemas/RawToolCall'
        - type: object
          properties:
            tool_info:
              $ref: '#/components/schemas/ToolInfo'
          required:
            - tool_info
    FinishReason:
      type:
        - string
        - 'null'
      enum:
        - stop
        - length
        - tool_calls
        - content_filter
        - function_call
    ModelMessageUsage:
      type: object
      properties:
        input_tokens:
          type: integer
          minimum: 0
        output_tokens:
          type: integer
          minimum: 0
        cache_read_tokens:
          type: integer
          minimum: 0
        cache_write_tokens:
          type: integer
          minimum: 0
        input_tokens_breakdown:
          type: object
          properties:
            harness:
              type: integer
              minimum: 0
            skills:
              type: integer
              minimum: 0
            instructions:
              type: integer
              minimum: 0
            tool_definitions:
              type: integer
              minimum: 0
            messages:
              type: integer
              minimum: 0
          required:
            - harness
            - skills
            - instructions
            - tool_definitions
            - messages
      required:
        - input_tokens
        - output_tokens
        - input_tokens_breakdown
    ExtendedChunkDeltaToolCall:
      allOf:
        - $ref: '#/components/schemas/ChatCompletionChunkDeltaToolCall'
        - type: object
          properties:
            tool_info:
              $ref: '#/components/schemas/ToolInfo'
            provider_specific_fields:
              type: object
              additionalProperties: {}
    AgentInfo:
      type: object
      properties:
        type:
          type: string
          enum:
            - dynamic
        name:
          type: string
        input:
          type: string
        model:
          type: string
          minLength: 1
      required:
        - type
        - name
        - input
    AgentParent:
      type: object
      properties:
        thread_id:
          type: string
        tool_call_id:
          type: string
      required:
        - thread_id
        - tool_call_id
    BaseThreadDoneEvent:
      type: object
      properties:
        parent:
          $ref: '#/components/schemas/AgentParent'
        thread_id:
          type: string
        title:
          type: string
      required:
        - thread_id
        - title
    ThreadState:
      oneOf:
        - $ref: '#/components/schemas/ThreadStateDone'
        - $ref: '#/components/schemas/ThreadStateError'
      discriminator:
        propertyName: status
        mapping:
          done:
            $ref: '#/components/schemas/ThreadStateDone'
          error:
            $ref: '#/components/schemas/ThreadStateError'
    BaseMCPAuthRequiredEvent:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the event
        created_at:
          type: string
        thread_id:
          type:
            - string
            - 'null'
      required:
        - id
        - created_at
        - thread_id
    MCPServerAuthInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        auth_url:
          type: string
      required:
        - id
        - name
        - auth_url
    MCPServerInitInfo:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        session_id:
          type: string
      required:
        - id
        - name
    ToolCallRef:
      type: object
      properties:
        id:
          type: string
        source_event_id:
          type: string
      required:
        - id
        - source_event_id
    TurnStateRunning:
      type: object
      properties:
        status:
          type: string
          enum:
            - running
      required:
        - status
    Subject:
      type: object
      properties:
        subject_id:
          type: string
        subject_type:
          type: string
        subject_slug:
          type:
            - string
            - 'null'
      required:
        - subject_id
        - subject_type
    TurnStateDone:
      type: object
      properties:
        status:
          type: string
          enum:
            - done
        output:
          allOf:
            - $ref: '#/components/schemas/ModelMessageEvent'
            - type:
                - object
                - 'null'
        required_actions:
          type: array
          items:
            $ref: '#/components/schemas/ActionRequiredEvent'
        completed_at:
          type: string
      required:
        - status
        - output
        - required_actions
        - completed_at
    TurnStateCancelled:
      type: object
      properties:
        status:
          type: string
          enum:
            - cancelled
        reason:
          $ref: '#/components/schemas/TurnStateCancelledReason'
        completed_at:
          type: string
      required:
        - status
        - reason
        - completed_at
    TurnStateError:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        message:
          type: string
        completed_at:
          type: string
      required:
        - status
        - message
        - completed_at
    UserMessageContentItem:
      oneOf:
        - $ref: '#/components/schemas/TextContent'
        - $ref: '#/components/schemas/FileContent'
      discriminator:
        propertyName: type
        mapping:
          text:
            $ref: '#/components/schemas/TextContent'
          file:
            $ref: '#/components/schemas/FileContent'
    ApprovalDecision:
      oneOf:
        - $ref: '#/components/schemas/ApprovalAllow'
        - $ref: '#/components/schemas/ApprovalDeny'
      discriminator:
        propertyName: status
        mapping:
          allow:
            $ref: '#/components/schemas/ApprovalAllow'
          deny:
            $ref: '#/components/schemas/ApprovalDeny'
    RawToolCall:
      allOf:
        - $ref: '#/components/schemas/ChatCompletionMessageToolCall'
        - type: object
          properties:
            provider_specific_fields:
              type: object
              additionalProperties: {}
    ToolInfo:
      oneOf:
        - $ref: '#/components/schemas/TrueFoundrySystemToolInfo'
        - $ref: '#/components/schemas/MCPToolInfo'
      discriminator:
        propertyName: type
        mapping:
          truefoundry-system:
            $ref: '#/components/schemas/TrueFoundrySystemToolInfo'
          mcp:
            $ref: '#/components/schemas/MCPToolInfo'
    ChatCompletionChunkDeltaToolCall:
      type: object
      properties:
        index:
          type: integer
          minimum: 0
        id:
          type: string
        type:
          type: string
          enum:
            - function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
      required:
        - index
    ThreadStateDone:
      type: object
      properties:
        status:
          type: string
          enum:
            - done
        output:
          $ref: '#/components/schemas/ModelMessageEvent'
      required:
        - status
        - output
    ThreadStateError:
      type: object
      properties:
        status:
          type: string
          enum:
            - error
        error:
          type: string
        output:
          $ref: '#/components/schemas/ModelMessageEvent'
      required:
        - status
        - error
    ActionRequiredEvent:
      oneOf:
        - $ref: '#/components/schemas/ToolApprovalRequiredEvent'
        - $ref: '#/components/schemas/ToolResponseRequiredEvent'
        - $ref: '#/components/schemas/MCPAuthRequiredEvent'
      discriminator:
        propertyName: type
        mapping:
          tool.approval_required:
            $ref: '#/components/schemas/ToolApprovalRequiredEvent'
          tool.response_required:
            $ref: '#/components/schemas/ToolResponseRequiredEvent'
          mcp.auth_required:
            $ref: '#/components/schemas/MCPAuthRequiredEvent'
    TurnStateCancelledReason:
      type: string
      enum:
        - server-execution-timeout
        - client-cancelled
        - cancelled-for-next-turn
      description: Reason for the cancellation.
    TextContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - text
        text:
          type: string
      required:
        - type
        - text
    FileContent:
      type: object
      properties:
        type:
          type: string
          enum:
            - file
        name:
          type: string
        data:
          type: string
          description: >-
            Data URI: `data:<mime>;base64,<payload>`. MIME type is parsed from
            the URI.
      required:
        - type
        - name
        - data
    ApprovalAllow:
      type: object
      properties:
        status:
          type: string
          enum:
            - allow
      required:
        - status
    ApprovalDeny:
      type: object
      properties:
        status:
          type: string
          enum:
            - deny
        reason:
          type: string
      required:
        - status
    ChatCompletionMessageToolCall:
      type: object
      properties:
        id:
          type: string
        type:
          type: string
          enum:
            - function
        function:
          type: object
          properties:
            name:
              type: string
            arguments:
              type: string
          required:
            - name
            - arguments
      required:
        - id
        - type
        - function
    TrueFoundrySystemToolInfo:
      type: object
      properties:
        type:
          type: string
          enum:
            - truefoundry-system
        name:
          type: string
      required:
        - type
        - name
    MCPToolInfo:
      type: object
      properties:
        type:
          type: string
          enum:
            - mcp
        server_id:
          type: string
        server_name:
          type: string
        name:
          type: string
      required:
        - type
        - server_id
        - server_name
        - name
  securitySchemes:
    AuthorizationBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT

````