openapi: 3.0.3
info:
  title: Agents API
  version: 1.0.0
  description: >
    AI Agents with tool-use capabilities. Create agents bound to AI providers,
    attach tools, run multi-step generations, and inspect execution traces.
  contact:
    name: SOAT API Support

servers:
  - url: '{baseUrl}'
    description: Base URL of your SOAT deployment (e.g. https://your-soat.com or http://localhost:5047)
    variables:
      baseUrl:
        description: The base URL of your SOAT deployment
        default: http://localhost:5047

tags:
  - name: Agents
    description: Manage AI agents
  - name: Agent Tools
    description: Manage agent tools
  - name: Agent Traces
    description: View agent traces
security:
  - bearerAuth: []

paths:
  /api/v1/agents/tools:
    post:
      tags:
        - Agent Tools
      summary: Create an agent tool
      description: Creates a new agent tool in the project.
      operationId: createAgentTool
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentToolRequest'
            examples:
              http:
                summary: HTTP tool
                value:
                  name: get-weather
                  type: http
                  description: Fetches current weather for a city
                  parameters:
                    type: object
                    properties:
                      city:
                        type: string
                    required:
                      - city
                  execute:
                    url: https://api.weather.example/v1/current?city={{city}}
              client:
                summary: Client tool
                value:
                  name: show-dialog
                  type: client
                  description: Displays a confirmation dialog to the user
                  parameters:
                    type: object
                    properties:
                      message:
                        type: string
              soat:
                summary: SOAT platform tool
                value:
                  name: soat-files
                  type: soat
                  actions:
                    - files:ListFiles
                    - files:GetFile
      responses:
        '201':
          description: Agent tool created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTool'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - Agent Tools
      summary: List agent tools
      description: Returns all agent tools in the project.
      operationId: listAgentTools
      parameters:
        - name: project_id
          in: query
          required: false
          schema:
            type: string
          description: Project public ID to filter by
      responses:
        '200':
          description: List of agent tools
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/AgentTool'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/agents/tools/{tool_id}:
    get:
      tags:
        - Agent Tools
      summary: Get an agent tool
      description: Returns a single agent tool by ID.
      operationId: getAgentTool
      parameters:
        - name: tool_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Agent tool
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTool'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Agent Tools
      summary: Update an agent tool
      description: Updates an existing agent tool.
      operationId: updateAgentTool
      parameters:
        - name: tool_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentToolRequest'
      responses:
        '200':
          description: Agent tool updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentTool'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Agent Tools
      summary: Delete an agent tool
      description: Deletes an agent tool by ID.
      operationId: deleteAgentTool
      parameters:
        - name: tool_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/agents:
    post:
      tags:
        - Agents
      summary: Create an agent
      description: Creates a new agent bound to an AI provider.
      operationId: createAgent
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentRequest'
            examples:
              minimal:
                summary: Minimal agent
                value:
                  ai_provider_id: aip_V1StGXR8Z5jdHi6B
              full:
                summary: Agent with tools and instructions
                value:
                  ai_provider_id: aip_V1StGXR8Z5jdHi6B
                  name: Research Assistant
                  instructions: You are a helpful research assistant.
                  model: gpt-4o
                  tool_ids:
                    - agt_tool_abc123
                  max_steps: 10
                  temperature: 0.7
      responses:
        '201':
          description: Agent created
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: AI provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
        - Agents
      summary: List agents
      description: Returns all agents in the project.
      operationId: listAgents
      parameters:
        - name: project_id
          in: query
          required: false
          schema:
            type: string
          description: Project public ID to filter by
      responses:
        '200':
          description: List of agents
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/agents/{agent_id}:
    get:
      tags:
        - Agents
      summary: Get an agent
      description: Returns a single agent by ID.
      operationId: getAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Agent details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
        - Agents
      summary: Update an agent
      description: Updates an existing agent.
      operationId: updateAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateAgentRequest'
      responses:
        '200':
          description: Agent updated
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Agent'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    delete:
      tags:
        - Agents
      summary: Delete an agent
      description: Deletes an agent by ID.
      operationId: deleteAgent
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      responses:
        '204':
          description: Deleted
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/agents/{agent_id}/generate:
    post:
      tags:
        - Agents
      summary: Run an agent generation
      description: >
        Sends messages to the agent, resolves its tools, and runs the AI model
        loop. Supports streaming via `stream: true`. Client tools pause the
        generation and return `requires_action`.
      operationId: createAgentGeneration
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateAgentGenerationRequest'
            examples:
              basic:
                summary: Simple generation
                value:
                  messages:
                    - role: user
                      content: What is the weather in Tokyo?
              streaming:
                summary: Streaming generation
                value:
                  messages:
                    - role: user
                      content: Summarize the latest report.
                  stream: true
      responses:
        '200':
          description: Generation result or SSE stream
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentGenerationResponse'
            text/event-stream:
              schema:
                type: string
                description: 'SSE stream of delta chunks ending with `data: [DONE]`.'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Agent or AI provider not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /api/v1/agents/{agent_id}/generate/{generation_id}/tool-outputs:
    post:
      tags:
        - Agents
      summary: Submit tool outputs for a paused generation
      description: >
        Resumes a generation that was paused due to client tool calls.
        Provide tool outputs for each pending tool call.
      operationId: submitAgentToolOutputs
      parameters:
        - name: agent_id
          in: path
          required: true
          schema:
            type: string
        - name: generation_id
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmitToolOutputsRequest'
      responses:
        '200':
          description: Generation result after resuming
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AgentGenerationResponse'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Agent or generation not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /api/v1/agents/{agent_id}/actors:
    post:
      tags:
        - Agents
      summary: Create an actor for an agent
      description: Creates a new actor associated with the specified agent
      operationId: createAgentActor
      parameters:
        - name: agent_id
          in: path
          required: true
          description: Agent ID
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - name
              properties:
                name:
                  type: string
                  example: 'Alice'
                type:
                  type: string
                  description: Optional actor type
                  example: 'customer'
                external_id:
                  type: string
                  description: Optional external identifier
                  example: '+15551234567'
                tags:
                  type: object
                  additionalProperties:
                    type: string
      responses:
        '201':
          description: Actor created
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  name:
                    type: string
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Agent not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: JWT token or sk_ api key
  schemas:
    AgentTool:
      type: object
      properties:
        id:
          type: string
          description: Public ID of the agent tool
          example: agt_tool_V1StGXR8Z5jdHi6B
        project_id:
          type: string
          description: Public ID of the owning project
          example: proj_V1StGXR8Z5jdHi6B
        name:
          type: string
          description: Tool name
          example: get-weather
        type:
          type: string
          enum:
            - http
            - client
            - mcp
            - soat
          description: Tool type
          example: http
        description:
          type: string
          nullable: true
          description: What the tool does (sent to the model)
        parameters:
          type: object
          nullable: true
          description: JSON Schema for tool input
        execute:
          type: object
          nullable: true
          description: >
            Execution config for http tools. Supported fields: `url` (required),
            `method` (default `POST`), and `headers`. The `url` may contain
            `{paramName}` placeholders (e.g. `/users/{userId}`) that are
            replaced at call time with the corresponding tool argument value
            (URL-encoded). Arguments consumed as path parameters are excluded
            from the query string and request body.
        mcp:
          type: object
          nullable: true
          description: MCP server config (url, headers)
        actions:
          type: array
          nullable: true
          items:
            type: string
          description: SOAT platform actions to expose
        preset_parameters:
          type: object
          nullable: true
          description: >-
            Fixed parameters merged into every soat tool call. Keys matching
            fields in the action's input schema are removed from the schema
            shown to the model and injected automatically at execution time.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateAgentToolRequest:
      type: object
      required:
        - name
      properties:
        project_id:
          type: string
          description: Public ID of the project
        name:
          type: string
          description: Tool name
        type:
          type: string
          enum:
            - http
            - client
            - mcp
            - soat
          description: Tool type (default http)
        description:
          type: string
          description: What the tool does
        parameters:
          type: object
          description: JSON Schema for tool input
        execute:
          type: object
          description: >
            Execution config for http tools. Supported fields: `url` (required),
            `method` (default `POST`), and `headers`. The `url` may contain
            `{paramName}` placeholders (e.g. `/users/{userId}`) that are
            replaced at call time with the corresponding tool argument value
            (URL-encoded). Arguments consumed as path parameters are excluded
            from the query string and request body.
        mcp:
          type: object
          description: MCP server config (url, headers)
        actions:
          type: array
          items:
            type: string
          description: SOAT platform actions
        preset_parameters:
          type: object
          description: >-
            Fixed parameters merged into every soat tool call. Keys matching
            fields in the action's input schema are removed from the schema
            shown to the model and injected automatically at execution time.

    UpdateAgentToolRequest:
      type: object
      properties:
        name:
          type: string
        type:
          type: string
          enum:
            - http
            - client
            - mcp
            - soat
        description:
          type: string
          nullable: true
        parameters:
          type: object
          nullable: true
        execute:
          type: object
          nullable: true
          description: >
            Execution config for http tools. Supported fields: `url` (required),
            `method` (default `POST`), and `headers`. The `url` may contain
            `{paramName}` placeholders (e.g. `/users/{userId}`) that are
            replaced at call time with the corresponding tool argument value
            (URL-encoded). Arguments consumed as path parameters are excluded
            from the query string and request body.
        mcp:
          type: object
          nullable: true
        actions:
          type: array
          nullable: true
          items:
            type: string
        preset_parameters:
          type: object
          nullable: true
          description: >-
            Fixed parameters merged into every soat tool call. Keys matching
            fields in the action's input schema are removed from the schema
            shown to the model and injected automatically at execution time.

    Agent:
      type: object
      properties:
        id:
          type: string
          description: Public ID of the agent
          example: agt_V1StGXR8Z5jdHi6B
        project_id:
          type: string
          description: Public ID of the owning project
        ai_provider_id:
          type: string
          description: Public ID of the AI provider
        name:
          type: string
          nullable: true
          description: Display name
        instructions:
          type: string
          nullable: true
          description: System instructions guiding behavior
        model:
          type: string
          nullable: true
          description: Model identifier
        tool_ids:
          type: array
          nullable: true
          items:
            type: string
          description: Public IDs of attached agent tools
        max_steps:
          type: integer
          nullable: true
          description: Maximum reasoning steps
        tool_choice:
          type: object
          nullable: true
          description: Tool choice strategy
        stop_conditions:
          type: array
          nullable: true
          items:
            type: object
          description: Stop conditions
        active_tool_ids:
          type: array
          nullable: true
          items:
            type: string
          description: Subset of toolIds active per step
        step_rules:
          type: array
          nullable: true
          items:
            type: object
          description: Per-step overrides
        boundary_policy:
          type: object
          nullable: true
          description: Allowed/denied SOAT actions
        temperature:
          type: number
          nullable: true
          description: Sampling temperature
        knowledge_config:
          type: object
          nullable: true
          description: Knowledge retrieval config injected before every generation
          properties:
            memory_ids:
              type: array
              items:
                type: string
            memory_tags:
              type: array
              items:
                type: string
            document_ids:
              type: array
              items:
                type: string
            document_paths:
              type: array
              items:
                type: string
            min_score:
              type: number
            limit:
              type: integer
            write_memory_id:
              type: string
              nullable: true
              description: Public ID of the memory the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time

    CreateAgentRequest:
      type: object
      required:
        - ai_provider_id
      properties:
        project_id:
          type: string
          description: Public ID of the project
        ai_provider_id:
          type: string
          description: Public ID of the AI provider
        name:
          type: string
        instructions:
          type: string
        model:
          type: string
        tool_ids:
          type: array
          items:
            type: string
        max_steps:
          type: integer
        tool_choice:
          type: object
        stop_conditions:
          type: array
          items:
            type: object
        active_tool_ids:
          type: array
          items:
            type: string
        step_rules:
          type: array
          items:
            type: object
        boundary_policy:
          type: object
        temperature:
          type: number
        knowledge_config:
          type: object
          properties:
            memory_ids:
              type: array
              items:
                type: string
            memory_tags:
              type: array
              items:
                type: string
            document_ids:
              type: array
              items:
                type: string
            document_paths:
              type: array
              items:
                type: string
            min_score:
              type: number
            limit:
              type: integer
            write_memory_id:
              type: string
              nullable: true
              description: Public ID of the memory the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.

    UpdateAgentRequest:
      type: object
      properties:
        ai_provider_id:
          type: string
        name:
          type: string
          nullable: true
        instructions:
          type: string
          nullable: true
        model:
          type: string
          nullable: true
        tool_ids:
          type: array
          nullable: true
          items:
            type: string
        max_steps:
          type: integer
          nullable: true
        tool_choice:
          type: object
          nullable: true
        stop_conditions:
          type: array
          nullable: true
          items:
            type: object
        active_tool_ids:
          type: array
          nullable: true
          items:
            type: string
        step_rules:
          type: array
          nullable: true
          items:
            type: object
        boundary_policy:
          type: object
          nullable: true
        temperature:
          type: number
          nullable: true
        knowledge_config:
          type: object
          nullable: true
          properties:
            memory_ids:
              type: array
              items:
                type: string
            memory_tags:
              type: array
              items:
                type: string
            document_ids:
              type: array
              items:
                type: string
            document_paths:
              type: array
              items:
                type: string
            min_score:
              type: number
            limit:
              type: integer
            write_memory_id:
              type: string
              nullable: true
              description: Public ID of the memory the agent can write to during generation. When set, a write_memory tool is automatically available to the agent.

    CreateAgentGenerationRequest:
      type: object
      required:
        - messages
      properties:
        messages:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - role
              - content
            properties:
              role:
                type: string
                enum:
                  - system
                  - user
                  - assistant
              content:
                type: string
        stream:
          type: boolean
          default: false
          description: When true the response is an SSE stream
        trace_id:
          type: string
          description: Optional trace ID to group generations
        parent_trace_id:
          type: string
          nullable: true
          description: The trace ID of the parent agent generation that triggered this one (for agent-to-agent calls)
        root_trace_id:
          type: string
          nullable: true
          description: The trace ID of the root generation in the call chain; if omitted, this generation is the root
        max_call_depth:
          type: integer
          minimum: 0
          default: 10
          description: Maximum nested agent-call depth; 0 short-circuits with a depth-guard response
        tool_context:
          type: object
          additionalProperties:
            type: string
          nullable: true
          description: Key-value pairs injected as context headers into all tool call requests made during this generation.

    SubmitToolOutputsRequest:
      type: object
      required:
        - tool_outputs
      properties:
        tool_outputs:
          type: array
          minItems: 1
          items:
            type: object
            required:
              - tool_call_id
              - output
            properties:
              tool_call_id:
                type: string
                description: ID of the tool call to respond to
              output:
                description: Result of the tool execution

    AgentGenerationResponse:
      type: object
      properties:
        id:
          type: string
          description: Public ID of the generation
          example: agt_gen_V1StGXR8Z5jdHi6B
        status:
          type: string
          enum:
            - completed
            - requires_action
          description: Generation status
        text:
          type: string
          nullable: true
          description: Final text output (when completed)
        tool_calls:
          type: array
          nullable: true
          items:
            type: object
            properties:
              tool_call_id:
                type: string
              tool_name:
                type: string
              args:
                type: object
          description: Pending tool calls (when requires_action)

    ErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          example: Unauthorized