openapi: 3.1.1
info:
  title: ACP - Agent Communication Protocol
  description: >-
    The Agent Communication Protocol (ACP) provides a standardized RESTful API for managing, orchestrating, and executing AI agents. It supports synchronous, asynchronous, and streamed agent interactions, with both stateless and stateful execution modes.
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.html
  version: 0.2.0
externalDocs:
  description: Comprehensive documentation for ACP
  url: https://agentcommunicationprotocol.dev
servers:
  - url: http://localhost:8000
tags:
  - name: agent
    description: Operations for listing, describing, and managing agent definitions and metadata.
  - name: run
    description: Operations for creating, managing, controlling, and monitoring agent runs and their lifecycles.
paths:
  /ping:
    get:
      summary: Ping
      description: Returns a ping.
      operationId: ping
      responses:
        "200":
          description: Ping successful
          content:
            application/json:
              schema:
                type: object
        default:
          $ref: "#/components/responses/Error"
  /agents:
    get:
      tags: [agent]
      summary: Agent Discovery
      description: Returns a list of agents.
      operationId: listAgents
      parameters:
        - name: limit
          in: query
          description: Maximum number of agents to return.
          schema:
            type: integer
            default: 10
            minimum: 1
            maximum: 1000
        - name: offset
          in: query
          description: Number of agents to skip.
          schema:
            type: integer
            default: 0
            minimum: 0
      responses:
        "200":
          description: List of agents
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentsListResponse"
        default:
          $ref: "#/components/responses/Error"
  /agents/{name}:
    get:
      tags: [agent]
      summary: Agent Manifest
      description: Returns a manifest of the specified agent.
      operationId: getAgent
      parameters:
        - name: name
          in: path
          required: true
          description: The name of the agent to retrieve.
          schema:
            $ref: "#/components/schemas/AgentName"
      responses:
        "200":
          description: Agent manifests
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/AgentManifest"
        default:
          $ref: "#/components/responses/Error"
  /runs:
    post:
      tags: [run]
      summary: Create a new run
      description: Create and start a new run for the specified agent.
      operationId: createRun
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunCreateRequest"
      responses:
        "200":
          description: Run started (streaming or immediate)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/Event"
        "202":
          description: Run accepted for processing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        default:
          $ref: "#/components/responses/Error"
  /runs/{run_id}:
    get:
      tags: [run]
      summary: Get run status
      description: Returns the current status and details of a run.
      operationId: getRun
      parameters:
        - name: run_id
          in: path
          required: true
          description: UUID of the run.
          schema:
            $ref: "#/components/schemas/RunId"
      responses:
        "200":
          description: Run status
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        default:
          $ref: "#/components/responses/Error"
    post:
      tags: [run]
      summary: Resume a run
      description: Resume a paused or awaiting run.
      operationId: resumeRun
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/RunResumeRequest"
      responses:
        "200":
          description: Run resumed (streaming or immediate)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
            text/event-stream:
              schema:
                $ref: "#/components/schemas/Event"
        "202":
          description: Resume request accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        default:
          $ref: "#/components/responses/Error"
  /runs/{run_id}/cancel:
    post:
      tags: [run]
      summary: Cancel a run
      description: Cancel the specified run.
      operationId: cancelRun
      parameters:
        - name: run_id
          in: path
          required: true
          description: UUID of the run to cancel.
          schema:
            $ref: "#/components/schemas/RunId"
      responses:
        "202":
          description: Cancel request accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Run"
        default:
          $ref: "#/components/responses/Error"
  /runs/{run_id}/events:
    get:
      tags: [run]
      summary: List run events
      description: Returns a list of events emitted by the run.
      operationId: listRunEvents
      parameters:
        - name: run_id
          in: path
          required: true
          description: UUID of the run.
          schema:
            $ref: "#/components/schemas/RunId"
      responses:
        "200":
          description: List of run events
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/RunEventsListResponse"
        default:
          $ref: "#/components/responses/Error"
  /session/{session_id}:
    get:
      tags: [session]
      summary: Session
      description: Returns details of the specified session.
      operationId: getSession
      parameters:
        - name: name
          in: path
          required: true
          description: The id of the session to retrieve.
          schema:
            $ref: "#/components/schemas/SessionId"
      responses:
        "200":
          description: Session details
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Session"
        default:
          $ref: "#/components/responses/Error"
components:
  responses:
    Error:
      description: Error response
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  schemas:
    Error:
      type: object
      properties:
        code:
          type: string
          enum:
            - server_error
            - invalid_input
            - not_found
        message:
          type: string
        data:
          type: object
          nullable: true
      required:
        - code
        - message
    SessionId:
      type: string
      format: uuid
      description: Identifier of a session
    RunId:
      type: string
      format: uuid
      description: Identifier of a run
    RunStatus:
      type: string
      enum:
        - created
        - in-progress
        - awaiting
        - cancelling
        - cancelled
        - completed
        - failed
      description: Status of the run
    RunMode:
      type: string
      enum: [sync, async, stream]
      description: Mode of the request
    CitationMetadata:
      type: object
      description: >
        Represents an inline citation, providing info about information source. This
        is supposed to be rendered as an inline icon, optionally marking a text
        range it belongs to.

        If CitationMetadata is included together with content in the message part,
        the citation belongs to that content and renders at the MessagePart position.
        This way may be used for non-text content, like images and files.

        Alternatively, `start_index` and `end_index` may define a text range,
        counting characters in the current Message across all MessageParts with
        content type `text/*`, where the citation will be rendered. If one of
        `start_index` and `end_index` is missing or their values are equal, the
        citation renders only as an inline icon at that position.

        If both `start_index` and `end_index` are not present and MessagePart has no
        content, the citation renders as inline icon only at the MessagePart position.
      properties:
        kind:
          type: string
          const: citation
          default: citation
        start_index:
          type: integer
          nullable: true
        end_index:
          type: integer
          nullable: true
        url:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        description:
          type: string
          nullable: true
          description: >
            Accompanying text, which may be a general description of the
            source document, or a specific snippet.
      required:
        - kind
    TrajectoryMetadata:
      type: object
      description: >
        Represents trajectory information for an agent's reasoning or tool execution
        steps. This metadata helps track the agent's decision-making process and
        provides transparency into how the agent arrived at its response.

        TrajectoryMetadata can capture either:
        1. A reasoning step with a message
        2. A tool execution with tool name, input, and output

        This information can be used for debugging, audit trails, and providing
        users with insight into the agent's thought process.
      properties:
        kind:
          type: string
          const: trajectory
          default: trajectory
        message:
          type: string
          nullable: true
          description: A reasoning step or thought in the agent's decision process.
        tool_name:
          type: string
          nullable: true
          description: Name of the tool that was executed.
        tool_input:
          type: object
          nullable: true
          description: Input parameters passed to the tool.
        tool_output:
          type: object
          nullable: true
          description: Output or result returned by the tool.
      required:
        - kind
    MessagePart:
      type: object
      properties:
        name:
          type: string
        content_type:
          type: string
          default: text/plain
        content:
          type: string
        content_encoding:
          type: string
          enum: [plain, base64]
          default: plain
        content_url:
          type: string
          format: uri
        metadata:
          oneOf:
            - $ref: "#/components/schemas/CitationMetadata"
            - $ref: "#/components/schemas/TrajectoryMetadata"
          nullable: true
      required:
        - content_type
      not:
        allOf:
          - required: [content]
          - required: [content_url]
      description: "A part of a message, containing a specific `content_type` and either inline `content` or `content_url`, or neither. Only one of `content` or `content_url` can be provided."
    Message:
      type: object
      required:
        - parts
        - role
      properties:
        role:
          type: string
          description: |
            Specifies the sender of the message. Allowed values:
            - `"user"` for messages sent by an end-user.
            - `"agent` for anonymous agent.
            - `"agent/{agent_name}"` for messages sent by an agent, where `{agent_name}` is the identifier of the agent.
          examples:
            - user
            - agent
            - agent/summarizer
            - agent/data_processor
          pattern: '^(user|agent(\/[a-zA-Z0-9_\-]+)?)$'
        parts:
          type: array
          items:
            $ref: "#/components/schemas/MessagePart"
          minItems: 1
          description: "Ordered sequence of message parts"
        created_at:
          type: string
          format: date-time
        completed_at:
          type: string
          format: date-time
    AwaitRequest:
      type: object
      description: Payload describing what is awaited from the client to continue the run.
    AwaitResume:
      type: object
      description: Payload sent by the client to resume an awaiting run.
    RunCreateRequest:
      type: object
      properties:
        agent_name:
          $ref: "#/components/schemas/AgentName"
        session_id:
          $ref: "#/components/schemas/SessionId"
        session:
          $ref: "#/components/schemas/Session"
        input:
          type: array
          items:
            $ref: "#/components/schemas/Message"
          minItems: 1
        mode:
          $ref: "#/components/schemas/RunMode"
      required:
        - agent_name
        - input
    RunResumeRequest:
      type: object
      properties:
        run_id:
          $ref: "#/components/schemas/RunId"
        await_resume:
          $ref: "#/components/schemas/AwaitResume"
        mode:
          $ref: "#/components/schemas/RunMode"
      required:
        - run_id
        - await_resume
        - mode
    RunEventsListResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: "#/components/schemas/Event"
      required:
        - events
    AgentsListResponse:
      type: object
      properties:
        agents:
          type: array
          items:
            $ref: "#/components/schemas/AgentManifest"
      required:
        - agents
    Run:
      type: object
      properties:
        agent_name:
          $ref: "#/components/schemas/AgentName"
        session_id:
          $ref: "#/components/schemas/SessionId"
        run_id:
          $ref: "#/components/schemas/RunId"
        status:
          $ref: "#/components/schemas/RunStatus"
        await_request:
          $ref: "#/components/schemas/AwaitRequest"
          nullable: true
        output:
          type: array
          items:
            $ref: "#/components/schemas/Message"
        error:
          $ref: "#/components/schemas/Error"
          nullable: true
        created_at:
          type: string
          format: date-time
        finished_at:
          type: string
          format: date-time
      required:
        - agent_name
        - run_id
        - status
        - output
        - created_at
    Session:
      type: object
      properties:
        id: 
          $ref: "#/components/schemas/SessionId"
        history:
          type: array
          items:
            type: string
            format: uri
        state:
          type: string
          format: uri
      required:
        - id
        - history
    MessageCreatedEvent:
      type: object
      properties:
        type:
          type: string
          const: message.created
        message:
          $ref: "#/components/schemas/Message"
      required:
        - type
        - message
    MessagePartEvent:
      type: object
      properties:
        type:
          type: string
          const: message.part
        part:
          $ref: "#/components/schemas/MessagePart"
      required:
        - type
        - part
    MessageCompletedEvent:
      type: object
      properties:
        type:
          type: string
          const: message.completed
        message:
          $ref: "#/components/schemas/Message"
      required:
        - type
        - message
    GenericEvent:
      type: object
      properties:
        type:
          type: string
          const: generic
        generic:
          type: object
      required:
        - type
        - generic
    RunCreatedEvent:
      type: object
      properties:
        type:
          type: string
          const: run.created
        run:
          $ref: "#/components/schemas/Run"
      required:
        - type
        - run
    RunInProgressEvent:
      type: object
      properties:
        type:
          type: string
          const: run.in-progress
        run:
          $ref: "#/components/schemas/Run"
      required:
        - type
        - run
    RunAwaitingEvent:
      type: object
      properties:
        type:
          type: string
          const: run.awaiting
        run:
          $ref: "#/components/schemas/Run"
      required:
        - type
        - run
    RunCompletedEvent:
      type: object
      properties:
        type:
          type: string
          const: run.completed
        run:
          $ref: "#/components/schemas/Run"
      required:
        - type
        - run
    RunCancelledEvent:
      type: object
      properties:
        type:
          type: string
          const: run.cancelled
        run:
          $ref: "#/components/schemas/Run"
      required:
        - type
        - run
    RunFailedEvent:
      type: object
      properties:
        type:
          type: string
          const: run.failed
        run:
          $ref: "#/components/schemas/Run"
      required:
        - type
        - run
    ErrorEvent:
      type: object
      properties:
        type:
          type: string
          const: error
        error:
          $ref: "#/components/schemas/Error"
      required:
        - type
        - error
    Event:
      oneOf:
        - $ref: "#/components/schemas/MessageCreatedEvent"
        - $ref: "#/components/schemas/MessagePartEvent"
        - $ref: "#/components/schemas/MessageCompletedEvent"
        - $ref: "#/components/schemas/GenericEvent"
        - $ref: "#/components/schemas/RunCreatedEvent"
        - $ref: "#/components/schemas/RunInProgressEvent"
        - $ref: "#/components/schemas/RunAwaitingEvent"
        - $ref: "#/components/schemas/RunCompletedEvent"
        - $ref: "#/components/schemas/RunFailedEvent"
        - $ref: "#/components/schemas/RunCancelledEvent"
        - $ref: "#/components/schemas/ErrorEvent"
    AgentName:
      type: string
      pattern: "^[a-z0-9]([-a-z0-9]*[a-z0-9])?$"
      minLength: 1
      maxLength: 63
      description: A unique identifier for the agent following the RFC 1123 DNS label naming convention.
      example: chat
    AgentManifest:
      type: object
      properties:
        name:
          $ref: "#/components/schemas/AgentName"
        description:
          type: string
          description: Human-readable description of the agent.
          example: Conversational agent with memory, supporting real-time search, Wikipedia lookups, and weather updates through integrated tools
        input_content_types:
          type: array
          minItems: 1
          description: >
            List of supported MIME content types for input Messages. Defines what formats of content the agent can consume.
          items:
            type: string
            examples:
              - "*/*"
              - image/*
              - text/plain
              - application/json
              - image/png
        output_content_types:
          type: array
          minItems: 1
          description: >
            List of supported MIME content types for output Messages. Defines what formats of content the agent can produce.
          items:
            type: string
            examples:
              - "*/*"
              - image/*
              - text/plain
              - application/json
              - image/png
        metadata:
          $ref: "#/components/schemas/Metadata"
        status:
          $ref: "#/components/schemas/Status"
      required:
        - name
        - description
        - input_content_types
        - output_content_types
    Status:
      type: object
      properties:
        avg_run_tokens:
          type: number
          minimum: 0
        avg_run_time_seconds:
          type: number
          format: float
          minimum: 0
        success_rate:
          type: number
          minimum: 0
          maximum: 100
          description: Percentage of successful runs (0-100).
      description: Real-time dynamic metrics and state provided by the system managing the agent.
    Tag:
      anyOf:
        - type: string
        - type: string
          enum:
            - Chat
            - RAG
            - Canvas
            - Code
            - Researcher
            - Orchestrator
      example: Chat
      description: Simple tag or enum for classifying agents.
    Metadata:
      type: object
      properties:
        annotations:
          type: object
          additionalProperties: true
          description: Key-value annotation metadata.
        documentation:
          type: string
          description: Full agent documentation in markdown.
          example: "The agent is a conversational system designed to process user messages, maintain context, and generate..."
        license:
          type: string
          description: SPDX license ID.
          example: Apache-2.0
        programming_language:
          type: string
          description: Programming language (per GitHub language support).
          example: Python
        natural_languages:
          type: array
          description: Supported human languages (ISO 639-1 codes).
          items:
            type: string
            example: en
        framework:
          type: string
          description: Agent framework, e.g. BeeAI, crewAI, Autogen, AG2.
          example: BeeAI
        capabilities:
          type: array
          description: >
            A structured list describing capabilities supported by the agent. Each capability includes a human-readable name and a brief description. This information might be consumed and interpreted by large language models (LLMs).
          items:
            type: object
            properties:
              name:
                type: string
                description: Human-readable name of the capability.
                example: "Conversational AI"
              description:
                type: string
                description: Brief description of what the capability provides or enables.
                example: "Handles multi-turn conversations with memory."
            required:
              - name
              - description
          example:
            - name: "Conversational AI"
              description: "Handles multi-turn conversations with memory."
            - name: "Vacation Request"
              description: "Handles submission and tracking of vacation requests."
        domains:
          type: array
          description: >
            Domains or functional areas applicable to the agent, such as 'finance', 'healthcare', 'supply-chain', or custom-defined domains relevant to your organization or team.
          items:
            type: string
          example: ["finance", "healthcare", "supply-chain"]
        tags:
          type: array
          items:
            $ref: "#/components/schemas/Tag"
        created_at:
          $ref: "#/components/schemas/Timestamp"
        updated_at:
          $ref: "#/components/schemas/Timestamp"
        author:
          $ref: "#/components/schemas/Person"
        contributors:
          type: array
          items:
            $ref: "#/components/schemas/Person"
        links:
          type: array
          items:
            $ref: "#/components/schemas/Link"
          example:
            - type: source-code
              url: https://github.com/i-am-bee/beeai-platform.git
            - type: homepage
              url: https://agentcommunicationprotocol.dev
        dependencies:
          type: array
          items:
            $ref: "#/components/schemas/AgentDependency"
        recommended_models:
          type: array
          items:
            type: string
            description: List of recommended model names (see providers such as Ollama, OpenAI, etc.).
          example:
            - llama3.3:70b-instruct-fp16
            - llama3.3
      description: Static details about the agent, for discovery, classification, and cataloging.
    GeneralSchema:
      oneOf:
        - $ref: "#/components/schemas/JsonSchema"
        - type: string
          enum: [chat, text]
          description: |
            Predefined schema types:
            - `chat`: Conversational input/output structured in a standard chat message format.
            - `text`: Simple plain text input/output without additional metadata.
    JsonSchema:
      type: object
      description: Any valid JSON Schema object.
    Link:
      type: object
      properties:
        type:
          type: string
          enum:
            - source-code
            - container-image
            - homepage
            - documentation
        url:
          type: string
          format: uri
      required:
        - type
        - url
    Timestamp:
      type: string
      format: date-time
      description: Timestamp in RFC3339/ISO8601 format.
    Person:
      type: object
      properties:
        name:
          type: string
          example: John Smith
        email:
          type: string
          format: email
          example: jsmith@example.com
        url:
          type: string
          format: uri
          example: https://example.com
      required:
        - name
    AgentDependency:
      type: object
      description: >
        **Experimental:** Represents a dependency required by the agent, specifying external resources or capabilities it relies upon, such as other agents, tools, or AI models.
      properties:
        type:
          type: string
          enum:
            - agent
            - tool
            - model
          description: |
            Type of dependency:
            - `agent`: Another agent instance required to fulfill certain functionalities.
            - `tool`: External tool or utility needed by the agent.
            - `model`: Specific AI model that the agent depends on.
          example: tool
        name:
          type: string
          description: >
            Identifier or name of the dependency, such as an agent name, tool identifier, or model name.
          example: weather