openapi.json

{
  "openapi": "3.1.1",
  "info": {
    "title": "Agent Connect Protocol",
    "version": "0.2.1"
  },
  "tags": [
    {
      "name": "Agents",
      "description": "Agents are AI workflows that can be configured and/or executed on this server.  This means that a client of this server can start a Run on any of the Agents supported by this server.\nEach agent may support different features of ACP, also each agent specifies the schemas of the objects carried by ACP for  configuration, input, output, interrupts and state. \nDetails of the ACP features and the schemas are kept in the ACP descriptor of the specific agent.  This object can be retrieved through this ACP interface or is found in the ACP extension of the agent record in the agent directory.\nSee `Agent` and `AgentACPDescriptor` models below for more info."
    },
    {
      "name": "Threads",
      "description": "If supported by the involved agents, Run can be grouped in Threads. \nWhen a run is executed on a thread is called Thread Run. At the end of a Thread Run, the server keeps a thread state associated to the thread.\nA thread keeps track of agent states at every step so that continuity of the context is preserved. Moreover, such a book-keeping enables us some granular controls like debugging, interrupting or replaying a run/invocation.\n\nA thread state is a data context defined by the developer and can be anything and it gets passed through from one invocation to another so that business logic is instrumented by data.\n\nA thread keeps track of the whole state history. At every step, it also applies a checkpoint, which is primarily a `uuid`, so that it is easier to refer to a chunk of the history.\n\nOne can easily query the last state, a specific state (by checkpoint id), the whole state history, or, a part of the history (from a checkpoint).\n\nSee `Thread`, `ThreadState` and `Checkpoint` models below for more info."
    },
    {
      "name": "Thread Runs",
      "description": "Thread Runs are runs created on a thread. \nA Thread Run can be created on a thread **only** if there is no run in the `pending` status on the same thread, i.e. if the thread is in the state `idle`\nNote that runs over the same thread can be executed on different agents, as long as the agents support the same thread state format.\nSee `Thread` and `RunCreateStateful` for more info."
    },
    {
      "name": "Stateless Runs",
      "description": "A Run represents an execution of an agent.\nThe output of a Run can be a final result or an interrupt.\nResult from a run can be retrieved by polling or by blocking and waiting for the result.\nSee `Run`  and `RunOutput` models below for more info."
    }
  ],
  "paths": {
    "/agents/search": {
      "post": {
        "tags": [
          "Agents"
        ],
        "summary": "Search Agents",
        "description": "Returns a list of agents matching the criteria provided in the request.\n\nThis endpoint also functions as the endpoint to list all agents.",
        "operationId": "search_agents",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AgentSearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Agent"
                  },
                  "type": "array",
                  "title": "Matching Agent List"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{agent_id}": {
      "get": {
        "tags": [
          "Agents"
        ],
        "summary": "Get Agent",
        "description": "Get an agent by ID.",
        "operationId": "get_agent_by_id",
        "parameters": [
          {
            "description": "The ID of the agent.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Agent Id",
              "description": "The ID of the agent."
            },
            "name": "agent_id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Agent"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/agents/{agent_id}/descriptor": {
      "get": {
        "tags": [
          "Agents"
        ],
        "summary": "Get Agent ACP Descriptor from its id",
        "description": "Get agent ACP descriptor by agent ID.",
        "operationId": "get_acp_descriptor_by_id",
        "parameters": [
          {
            "description": "The ID of the agent.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Agent Id",
              "description": "The ID of the agent."
            },
            "name": "agent_id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AgentACPDescriptor"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads": {
      "post": {
        "tags": [
          "Threads"
        ],
        "summary": "Create an empty Thread",
        "description": "Create a new thread. ",
        "operationId": "create_thread",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thread"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/search": {
      "post": {
        "tags": [
          "Threads"
        ],
        "summary": "Search Threads",
        "description": "Search for threads.\n\nThis endpoint also functions as the endpoint to list all threads.",
        "operationId": "search_threads",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadSearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/Thread"
                  },
                  "type": "array",
                  "title": "Response Search Agents Agents Search Post"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/{thread_id}/history": {
      "get": {
        "tags": [
          "Threads"
        ],
        "summary": "Get Thread History",
        "description": "Get all past states for a thread.",
        "operationId": "get_thread_history",
        "parameters": [
          {
            "description": "The ID of the thread.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Thread Id",
              "description": "The ID of the thread."
            },
            "name": "thread_id",
            "in": "path"
          },
          {
            "required": false,
            "schema": {
              "type": "integer",
              "title": "Limit",
              "default": 10
            },
            "name": "limit",
            "in": "query"
          },
          {
            "required": false,
            "schema": {
              "type": "string",
              "title": "Before"
            },
            "name": "before",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/ThreadState"
                  },
                  "type": "array"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/{thread_id}/copy": {
      "post": {
        "tags": [
          "Threads"
        ],
        "summary": "Copy Thread",
        "description": "Create a new thread with a copy of the state and checkpoints from an existing thread.",
        "operationId": "copy_thread",
        "parameters": [
          {
            "description": "The ID of the thread.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Thread Id",
              "description": "The ID of the thread."
            },
            "name": "thread_id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thread"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/{thread_id}": {
      "parameters": [
        {
          "description": "The ID of the thread.",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID",
            "description": "The ID of the thread."
          },
          "name": "thread_id",
          "in": "path"
        }
      ],
      "get": {
        "tags": [
          "Threads"
        ],
        "summary": "Get Thread",
        "description": "Get a thread from its ID. ",
        "operationId": "get_thread",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thread"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Threads"
        ],
        "summary": "Delete a thread. If the thread contains any pending run, deletion fails.",
        "description": "Delete a thread.",
        "operationId": "delete_thread",
        "responses": {
          "204": {
            "description": "Success"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "patch": {
        "tags": [
          "Threads"
        ],
        "summary": "Patch Thread",
        "description": "Update a thread.",
        "operationId": "patch_thread",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ThreadPatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Thread"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/{thread_id}/runs": {
      "parameters": [
        {
          "description": "The ID of the thread.",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid",
            "title": "Thread ID",
            "description": "The ID of the thread."
          },
          "name": "thread_id",
          "in": "path"
        }
      ],
      "get": {
        "tags": [
          "Thread Runs"
        ],
        "summary": "List Runs for a thread",
        "description": "List runs for a thread.",
        "operationId": "list_thread_runs",
        "parameters": [
          {
            "required": false,
            "schema": {
              "type": "integer",
              "title": "Limit",
              "default": 10
            },
            "name": "limit",
            "in": "query"
          },
          {
            "required": false,
            "schema": {
              "type": "integer",
              "title": "Offset",
              "default": 0
            },
            "name": "offset",
            "in": "query"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/RunStateful"
                  },
                  "type": "array"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Thread Runs"
        ],
        "summary": "Create a Background Run on a thread",
        "description": "Create a run on a thread, return the run ID immediately. Don't wait for the final run output.",
        "operationId": "create_thread_run",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunCreateStateful"
              }
            }
          },
          "required": true
        },
        "callbacks": {
          "runstatuschange": {
            "{$request.body#/webhook}": {
              "post": {
                "requestBody": {
                  "required": true,
                  "content": {
                    "application/json": {
                      "schema": {
                        "$ref": "#/components/schemas/RunStateful"
                      }
                    }
                  }
                },
                "responses": {
                  "200": {
                    "description": "Your server returns this code if it accepts the callback"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunStateful"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/{thread_id}/runs/stream": {
      "post": {
        "tags": [
          "Thread Runs"
        ],
        "summary": "Create a run on a thread and stream its output",
        "description": "Create a run on a thread and join its output stream. See 'GET /runs/{run_id}/stream' for details on the return values.",
        "operationId": "create_and_stream_thread_run_output",
        "parameters": [
          {
            "description": "The ID of the thread.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Thread Id",
              "description": "The ID of the thread."
            },
            "name": "thread_id",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunCreateStateful"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Stream of agent results either as `ValueRunResultUpdate` objects or `CustomRunResultUpdate` objects, according to the specific streaming mode requested. Note that the stream of events is carried using the format specified in SSE spec `text/event-stream`",
            "content": {
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/RunOutputStream"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/{thread_id}/runs/wait": {
      "post": {
        "tags": [
          "Thread Runs"
        ],
        "summary": "Create a run on a thread and block waiting for the result of the run",
        "description": "Create a run on a thread and block waiting for its output. See 'GET /runs/{run_id}/wait' for details on the return values.",
        "operationId": "create_and_wait_for_thread_run_output",
        "parameters": [
          {
            "description": "The ID of the thread.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Thread Id",
              "description": "The ID of the thread."
            },
            "name": "thread_id",
            "in": "path"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunCreateStateful"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunWaitResponseStateful"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/{thread_id}/runs/{run_id}/wait": {
      "get": {
        "tags": [
          "Thread Runs"
        ],
        "summary": "Blocks waiting for the result of the run.",
        "description": "Blocks waiting for the result of the run. See 'GET /runs/{run_id}/wait' for details on the return values.",
        "operationId": "wait_for_thread_run_output",
        "parameters": [
          {
            "description": "The ID of the thread.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Thread Id",
              "description": "The ID of the thread."
            },
            "name": "thread_id",
            "in": "path"
          },
          {
            "description": "The ID of the run.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Run Id",
              "description": "The ID of the run."
            },
            "name": "run_id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunWaitResponseStateful"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/{thread_id}/runs/{run_id}": {
      "parameters": [
        {
          "description": "The ID of the thread.",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid",
            "title": "Thread Id",
            "description": "The ID of the thread."
          },
          "name": "thread_id",
          "in": "path"
        },
        {
          "description": "The ID of the run.",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid",
            "title": "Run Id",
            "description": "The ID of the run."
          },
          "name": "run_id",
          "in": "path"
        }
      ],
      "get": {
        "tags": [
          "Thread Runs"
        ],
        "summary": "Get Run",
        "description": "Get a run by ID.",
        "operationId": "get_thread_run",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunStateful"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Thread Runs"
        ],
        "summary": "Resume an interrupted Run",
        "description": "Provide the needed input to a run to resume its execution. Can only be called for runs that are in the interrupted state Schema of the provided input must match with the schema specified in the agent specs under interrupts for the interrupt type the agent generated for this specific interruption.",
        "operationId": "resume_thread_run",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResumePayloadSchema"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunStateful"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Thread Runs"
        ],
        "summary": "Delete Run",
        "description": "Delete a run by ID.",
        "operationId": "delete_thread_run",
        "responses": {
          "204": {
            "description": "Success"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/{thread_id}/runs/{run_id}/stream": {
      "get": {
        "tags": [
          "Thread Runs"
        ],
        "summary": "Stream output from Run",
        "description": "Join the output stream of an existing run. See 'GET /runs/{run_id}/stream' for details on the return values.",
        "operationId": "stream_thread_run_output",
        "parameters": [
          {
            "description": "The ID of the thread.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Thread Id",
              "description": "The ID of the thread."
            },
            "name": "thread_id",
            "in": "path"
          },
          {
            "description": "The ID of the run.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Run Id",
              "description": "The ID of the run."
            },
            "name": "run_id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Stream of agent results either as `ValueRunResultUpdate` objects or `CustomRunResultUpdate` objects, according to the specific streaming mode requested. Note that the stream of events is carried using the format specified in SSE spec `text/event-stream`",
            "content": {
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/RunOutputStream"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/threads/{thread_id}/runs/{run_id}/cancel": {
      "post": {
        "tags": [
          "Thread Runs"
        ],
        "summary": "Cancel Run",
        "operationId": "cancel_thread_run",
        "parameters": [
          {
            "description": "The ID of the thread.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Thread Id",
              "description": "The ID of the thread."
            },
            "name": "thread_id",
            "in": "path"
          },
          {
            "description": "The ID of the run.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Run Id",
              "description": "The ID of the run."
            },
            "name": "run_id",
            "in": "path"
          },
          {
            "required": false,
            "schema": {
              "type": "boolean",
              "title": "Wait",
              "default": false
            },
            "name": "wait",
            "in": "query"
          },
          {
            "description": "Action to take when cancelling the run. Possible values are `interrupt` or `rollback`. `interrupt` will simply cancel the run. `rollback` will cancel the run and delete the run and associated checkpoints afterwards.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "interrupt",
                "rollback"
              ],
              "title": "Action",
              "default": "interrupt"
            },
            "name": "action",
            "in": "query"
          }
        ],
        "responses": {
          "204": {
            "description": "Success"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/runs": {
      "post": {
        "tags": [
          "Stateless Runs"
        ],
        "summary": "Create a Background stateless Run",
        "description": "Create a stateless run, return the run ID immediately. Don't wait for the final run output.",
        "operationId": "create_stateless_run",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunCreateStateless"
              }
            }
          },
          "required": true
        },
        "callbacks": {
          "runstatuschange": {
            "{$request.body#/webhook}": {
              "post": {
                "requestBody": {
                  "required": true,
                  "content": {
                    "application/json": {
                      "schema": {
                        "$ref": "#/components/schemas/RunStateless"
                      }
                    }
                  }
                },
                "responses": {
                  "200": {
                    "description": "Your server returns this code if it accepts the callback"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunStateless"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/runs/search": {
      "post": {
        "tags": [
          "Stateless Runs"
        ],
        "summary": "Search Stateless Runs",
        "description": "Search for stateless run.\n\nThis endpoint also functions as the endpoint to list all stateless Runs.",
        "operationId": "search_stateless_runs",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunSearchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/RunStateless"
                  },
                  "type": "array",
                  "title": "Run Search Response"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/runs/stream": {
      "post": {
        "tags": [
          "Stateless Runs"
        ],
        "summary": "Create a stateless run and stream its output",
        "description": "Create a stateless run and join its output stream. See 'GET /runs/{run_id}/stream' for details on the return values.",
        "operationId": "create_and_stream_stateless_run_output",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunCreateStateless"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Stream of agent results either as `ValueRunResultUpdate` objects or `CustomRunResultUpdate` objects, according to the specific streaming mode requested. Note that the stream of events is carried using the format specified in SSE spec `text/event-stream`",
            "content": {
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/RunOutputStream"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/runs/wait": {
      "post": {
        "tags": [
          "Stateless Runs"
        ],
        "summary": "Create a stateless run and wait for its output",
        "description": "Create a stateless run and wait for its output. See 'GET /runs/{run_id}/wait' for details on the return values.",
        "operationId": "create_and_wait_for_stateless_run_output",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RunCreateStateless"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunWaitResponseStateless"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/runs/{run_id}/wait": {
      "get": {
        "tags": [
          "Stateless Runs"
        ],
        "summary": "Blocks waiting for the result of the run.",
        "description": "Blocks waiting for the result of the run. The output can be:\n  * an interrupt, this happens when the agent run status is `interrupted`\n  * the final result of the run, this happens when the agent run status is `success`\n  * an error, this happens when the agent run status is `error` or `timeout`\n\n\nThis call blocks until the output is available.",
        "operationId": "wait_for_stateless_run_output",
        "parameters": [
          {
            "description": "The ID of the run.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Run Id",
              "description": "The ID of the run."
            },
            "name": "run_id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunWaitResponseStateless"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/runs/{run_id}": {
      "parameters": [
        {
          "description": "The ID of the run.",
          "required": true,
          "schema": {
            "type": "string",
            "format": "uuid",
            "title": "Run Id",
            "description": "The ID of the run."
          },
          "name": "run_id",
          "in": "path"
        }
      ],
      "get": {
        "tags": [
          "Stateless Runs"
        ],
        "summary": "Get Run",
        "description": "Get a stateless run by ID.",
        "operationId": "get_stateless_run",
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunStateless"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "post": {
        "tags": [
          "Stateless Runs"
        ],
        "summary": "Resume an interrupted Run",
        "description": "Provide the needed input to a run to resume its execution. Can only be called for runs that are in the interrupted state Schema of the provided input must match with the schema specified in the agent specs under interrupts for the interrupt type the agent generated for this specific interruption.",
        "operationId": "resume_stateless_run",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResumePayloadSchema"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunStateless"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "409": {
            "description": "Conflict",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      },
      "delete": {
        "tags": [
          "Stateless Runs"
        ],
        "summary": "Delete Stateless Run",
        "description": "Delete a stateless run by ID.",
        "operationId": "delete_stateless_run",
        "responses": {
          "204": {
            "description": "Success"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/runs/{run_id}/stream": {
      "get": {
        "tags": [
          "Stateless Runs"
        ],
        "summary": "Stream output from Stateless Run",
        "description": "Join the output stream of an existing run. This endpoint streams output in real-time from a run. Only output produced after this endpoint is called will be streamed.",
        "operationId": "stream_stateless_run_output",
        "parameters": [
          {
            "description": "The ID of the run.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Run Id",
              "description": "The ID of the run."
            },
            "name": "run_id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Stream of agent results either as `ValueRunResultUpdate` objects or `CustomRunResultUpdate` objects, according to the specific streaming mode requested. Note that the stream of events is carried using the format specified in SSE spec `text/event-stream`",
            "content": {
              "text/event-stream": {
                "schema": {
                  "$ref": "#/components/schemas/RunOutputStream"
                }
              }
            }
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/runs/{run_id}/cancel": {
      "post": {
        "tags": [
          "Stateless Runs"
        ],
        "summary": "Cancel Stateless Run",
        "operationId": "cancel_stateless_run",
        "parameters": [
          {
            "description": "The ID of the run.",
            "required": true,
            "schema": {
              "type": "string",
              "format": "uuid",
              "title": "Run Id",
              "description": "The ID of the run."
            },
            "name": "run_id",
            "in": "path"
          },
          {
            "required": false,
            "schema": {
              "type": "boolean",
              "title": "Wait",
              "default": false
            },
            "name": "wait",
            "in": "query"
          },
          {
            "description": "Action to take when cancelling the run. Possible values are `interrupt` or `rollback`. `interrupt` will simply cancel the run. `rollback` will cancel the run and delete the run and associated checkpoints afterwards.",
            "required": false,
            "schema": {
              "type": "string",
              "enum": [
                "interrupt",
                "rollback"
              ],
              "title": "Action",
              "default": "interrupt"
            },
            "name": "action",
            "in": "query"
          }
        ],
        "responses": {
          "204": {
            "description": "Success"
          },
          "404": {
            "description": "Not Found",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          },
          "422": {
            "description": "Validation Error",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ErrorResponse"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Agent": {
        "title": "Agent",
        "description": "A description of an agent supported by this server",
        "type": "object",
        "properties": {
          "agent_id": {
            "type": "string",
            "format": "uuid",
            "title": "Agent Id",
            "description": "Unique identifier of the agent in this server."
          },
          "metadata": {
            "$ref": "#/components/schemas/AgentMetadata"
          }
        },
        "required": [
          "agent_id",
          "metadata"
        ]
      },
      "AgentMetadata": {
        "title": "Agent Metadata",
        "description": "Basic information associated to the agent",
        "type": "object",
        "properties": {
          "ref": {
            "$ref": "#/components/schemas/AgentRef"
          },
          "description": {
            "description": "Description of this agent, which should include what the intended use is, what tasks it accomplishes and how uses input and configs to produce the output and any other side effect",
            "title": "Description",
            "type": "string"
          }
        },
        "required": [
          "ref",
          "description"
        ]
      },
      "AgentRef": {
        "title": "Agent Reference",
        "description": "Reference to an Agent Record in the Agent Directory, it includes name, version and a locator.",
        "type": "object",
        "properties": {
          "name": {
            "description": "Name of the agent that identifies the agent in its record",
            "title": "Name",
            "type": "string"
          },
          "version": {
            "description": "Version of the agent in its record. Should be formatted according to semantic versioning (https://semver.org)",
            "title": "Version",
            "type": "string"
          },
          "url": {
            "title": "Agent Record URL",
            "description": "URL of the record. Can be a network location, i.e. an entry in the Agent Directory or a file.",
            "type": "string",
            "format": "uri"
          }
        },
        "required": [
          "name",
          "version"
        ]
      },
      "AgentACPDescriptor": {
        "title": "Agent ACP Descriptor",
        "description": "Describe all the ACP specs of an agent, including schemas and protocol features.",
        "type": "object",
        "properties": {
          "metadata": {
            "$ref": "#/components/schemas/AgentMetadata"
          },
          "specs": {
            "$ref": "#/components/schemas/AgentACPSpec"
          }
        },
        "required": [
          "metadata",
          "specs"
        ]
      },
      "AgentACPSpec": {
        "title": "Agent ACP Specs",
        "description": "Specification of agent capabilities, config, input, output, and interrupts",
        "type": "object",
        "properties": {
          "capabilities": {
            "type": "object",
            "title": "Agent Capabilities",
            "description": "Declares what invocation features this agent is capable of.",
            "properties": {
              "threads": {
                "type": "boolean",
                "title": "Thread Support",
                "default": false,
                "description": "This is `true` if the agent supports run threads. If this is `false`, then the threads tagged with `Threads` are not available. If missing, it means `false`"
              },
              "interrupts": {
                "type": "boolean",
                "title": "Interrupt Support",
                "default": false,
                "description": "This is `true` if the agent runs can interrupt to request additional input and can be subsequently resumed. If missing, it means `false`"
              },
              "callbacks": {
                "type": "boolean",
                "title": "Callback Support",
                "default": false,
                "description": "This is `true` if the agent supports a webhook to report run results. If this is `false`, providing a `webhook` at run creation has no effect. If missing, it means `false`"
              },
              "streaming": {
                "type": "object",
                "title": "Streaming Modes",
                "description": "Supported streaming modes. If missing, streaming is not supported.  If no mode is supported attempts to stream output will result in an error.",
                "properties": {
                  "values": {
                    "type": "boolean",
                    "title": "Values Streaming",
                    "description": "This is `true` if the agent supports values streaming. If `false` or missing, values streaming is not supported. Values streaming consists of a stream of objects of type `ValueRunResultUpdate`, where each one sent over the stream fully replace the previous one."
                  },
                  "custom": {
                    "type": "boolean",
                    "title": "Custom Objects Streaming",
                    "description": "This is `true` if the agent supports custom objects streaming. If `false` or missing, custom streaming is not supported. Custom Objects streaming consists of a stream of object whose schema is specified by the agent ACP descriptor under `specs.custom_streaming_update`."
                  }
                }
              }
            }
          },
          "input": {
            "type": "object",
            "description": "This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object",
            "examples": [
              {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "address": {
                    "type": "string"
                  },
                  "age": {
                    "type": "integer",
                    "format": "int32",
                    "minimum": 0
                  }
                }
              }
            ]
          },
          "output": {
            "type": "object",
            "description": "This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object",
            "examples": [
              {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": null,
                "name": {
                  "type": "string"
                },
                "address": {
                  "type": "string"
                },
                "age": {
                  "type": "integer",
                  "format": "int32",
                  "minimum": 0
                }
              }
            ]
          },
          "custom_streaming_update": {
            "type": "object",
            "description": "This describes the format of an Update in the streaming.  Must be specified if `streaming.custom` capability is true and cannot be specified otherwise. Format follows: https://spec.openapis.org/oas/v3.1.1.html#schema-object",
            "examples": [
              {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": null,
                "name": {
                  "type": "string"
                },
                "address": {
                  "type": "string"
                },
                "age": {
                  "type": "integer",
                  "format": "int32",
                  "minimum": 0
                }
              }
            ]
          },
          "thread_state": {
            "type": "object",
            "description": "This describes the format of ThreadState.  Cannot be specified if `threads` capability is false. If not specified, when `threads` capability is true, then the API to retrieve ThreadState from a Thread or a Run is not available. This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object",
            "examples": [
              {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": null,
                "name": {
                  "type": "string"
                },
                "address": {
                  "type": "string"
                },
                "age": {
                  "type": "integer",
                  "format": "int32",
                  "minimum": 0
                }
              }
            ]
          },
          "config": {
            "type": "object",
            "description": "This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object",
            "examples": [
              {
                "type": "object",
                "required": [
                  "name"
                ],
                "properties": null,
                "name": {
                  "type": "string"
                },
                "address": {
                  "type": "string"
                },
                "age": {
                  "type": "integer",
                  "format": "int32",
                  "minimum": 0
                }
              }
            ]
          },
          "interrupts": {
            "type": "array",
            "description": "List of possible interrupts that can be provided by the agent. If `interrupts` capability is true, this needs to have at least one item.",
            "items": {
              "type": "object",
              "properties": {
                "interrupt_type": {
                  "description": "Name of this interrupt type. Needs to be unique in the list of interrupts.",
                  "title": "Interrupt Type Name",
                  "type": "string"
                },
                "interrupt_payload": {
                  "type": "object",
                  "description": "This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object",
                  "examples": [
                    {
                      "type": "object",
                      "required": [
                        "name"
                      ],
                      "properties": null,
                      "name": {
                        "type": "string"
                      },
                      "address": {
                        "type": "string"
                      },
                      "age": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                      }
                    }
                  ]
                },
                "resume_payload": {
                  "type": "object",
                  "description": "This object contains an instance of an OpenAPI schema object, formatted as per the OpenAPI specs: https://spec.openapis.org/oas/v3.1.1.html#schema-object",
                  "examples": [
                    {
                      "type": "object",
                      "required": [
                        "name"
                      ],
                      "properties": null,
                      "name": {
                        "type": "string"
                      },
                      "address": {
                        "type": "string"
                      },
                      "age": {
                        "type": "integer",
                        "format": "int32",
                        "minimum": 0
                      }
                    }
                  ]
                }
              },
              "required": [
                "interrupt_type",
                "resume_payload",
                "interrupt_payload"
              ]
            }
          }
        },
        "required": [
          "capabilities",
          "input",
          "output",
          "config"
        ]
      },
      "AgentSearchRequest": {
        "properties": {
          "name": {
            "type": "string",
            "title": "Name",
            "description": "Match all agents with the name specified."
          },
          "version": {
            "type": "string",
            "title": "Version",
            "description": "Match all agents with the version specified. Formatted according to semantic versioning (https://semver.org)"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Maximum number to return.",
            "default": 10,
            "minimum": 1,
            "maximum": 1000
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset to start from.",
            "default": 0,
            "minimum": 0
          }
        },
        "type": "object",
        "title": "AgentSearchRequest",
        "description": "Payload for listing agents."
      },
      "Run": {
        "title": "Agent Run",
        "description": "Holds common information of a run",
        "properties": {
          "run_id": {
            "type": "string",
            "format": "uuid",
            "title": "Run Id",
            "description": "The ID of the run."
          },
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Agent ID",
            "description": "Optional Thread ID wher the Run belongs to. This is populated only for runs on agents agents supporting Threads."
          },
          "agent_id": {
            "type": "string",
            "format": "uuid",
            "title": "Agent Id",
            "description": "The agent that was used for this run."
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At",
            "description": "The time the run was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At",
            "description": "The last time the run was updated."
          },
          "status": {
            "$ref": "#/components/schemas/RunStatus",
            "title": "Status",
            "description": "The status of the run. One of 'pending', 'error', 'success', 'timeout', 'interrupted'."
          }
        },
        "required": [
          "run_id",
          "agent_id",
          "created_at",
          "updated_at",
          "status"
        ]
      },
      "RunStateless": {
        "title": "Agent Run Stateless",
        "description": "Holds all the information of a stateless run",
        "allOf": [
          {
            "$ref": "#/components/schemas/Run"
          },
          {
            "type": "object",
            "properties": {
              "creation": {
                "$ref": "#/components/schemas/RunCreateStateless",
                "title": "Creation",
                "description": ""
              }
            },
            "required": [
              "creation"
            ]
          }
        ]
      },
      "RunStateful": {
        "title": "Agent Run Stateful",
        "description": "Holds all the information of a stateful run",
        "allOf": [
          {
            "$ref": "#/components/schemas/Run"
          },
          {
            "type": "object",
            "properties": {
              "creation": {
                "$ref": "#/components/schemas/RunCreateStateful",
                "title": "Creation",
                "description": ""
              }
            },
            "required": [
              "creation"
            ]
          }
        ]
      },
      "RunCreateStateful": {
        "allOf": [
          {
            "$ref": "#/components/schemas/RunCreate"
          },
          {
            "type": "object",
            "properties": {
              "stream_subgraphs": {
                "type": "boolean",
                "title": "Stream Subgraphs",
                "description": "Whether to stream output from subgraphs.",
                "default": false
              },
              "if_not_exists": {
                "type": "string",
                "enum": [
                  "create",
                  "reject"
                ],
                "title": "If Not Exists",
                "description": "How to handle missing thread. Must be either 'reject' (raise error if missing), or 'create' (create new thread).",
                "default": "reject"
              }
            }
          }
        ],
        "title": "RunCreateStateful",
        "description": "Payload for creating a stateful run."
      },
      "RunWaitResponseStateful": {
        "type": "object",
        "properties": {
          "run": {
            "$ref": "#/components/schemas/RunStateful",
            "title": "Run",
            "description": "The run information."
          },
          "output": {
            "$ref": "#/components/schemas/RunOutput"
          }
        }
      },
      "RunWaitResponseStateless": {
        "type": "object",
        "properties": {
          "run": {
            "$ref": "#/components/schemas/RunStateless",
            "title": "Run",
            "description": "The run information."
          },
          "output": {
            "$ref": "#/components/schemas/RunOutput"
          }
        }
      },
      "RunCreateStateless": {
        "allOf": [
          {
            "$ref": "#/components/schemas/RunCreate"
          },
          {
            "type": "object",
            "properties": {
              "on_completion": {
                "type": "string",
                "enum": [
                  "delete",
                  "keep"
                ],
                "title": "On Completion",
                "description": "Whether to delete or keep the thread created for a stateless run. Must be one of 'delete' or 'keep'.",
                "default": "delete"
              }
            }
          }
        ],
        "title": "RunCreateStateless",
        "description": "Payload for creating a stateless run."
      },
      "ThreadSearchRequest": {
        "properties": {
          "metadata": {
            "type": "object",
            "title": "Metadata Filter",
            "description": "Matches all threads for which metadata has  keys and values equal to those specified in this object."
          },
          "values": {
            "type": "object",
            "title": "Values",
            "description": "State values to filter on."
          },
          "status": {
            "$ref": "#/components/schemas/ThreadStatus"
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Maximum number to return.",
            "default": 10,
            "minimum": 1,
            "maximum": 1000
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset to start from.",
            "default": 0,
            "minimum": 0
          }
        },
        "type": "object",
        "title": "Thread Search Request",
        "description": "Payload for listing threads."
      },
      "Thread": {
        "type": "object",
        "title": "Thread",
        "description": "Represents a collection of consecutive runs over a thread.  Thread is associated with a state. Runs for a thread can potentially happen across different agents, if the state format is compatible.",
        "properties": {
          "thread_id": {
            "type": "string",
            "title": "Thread ID",
            "description": "unique identifier of a thread"
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "title": "Created At",
            "description": "The time the thread was created."
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "title": "Updated At",
            "description": "The last time the thread was updated."
          },
          "metadata": {
            "type": "object",
            "title": "Metadata",
            "description": "Free form metadata for this thread"
          },
          "status": {
            "type": "string",
            "enum": [
              "idle",
              "busy",
              "interrupted",
              "error"
            ],
            "title": "Status",
            "description": "The status of the thread."
          },
          "values": {
            "title": "Values",
            "description": "The current state of the thread.",
            "$ref": "#/components/schemas/ThreadStateSchema"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            },
            "title": "Messages",
            "description": "The current Messages of the thread. If messages are contained in Thread.values, implementations should remove them from values when returning messages. When this key isn't present it means the thread/agent doesn't support messages."
          }
        },
        "required": [
          "thread_id",
          "created_at",
          "updated_at",
          "metadata",
          "status"
        ]
      },
      "ThreadCheckpoint": {
        "properties": {
          "checkpoint_id": {
            "type": "string",
            "format": "uuid",
            "title": "Checkpoint Id",
            "description": "The ID of the checkpoint."
          }
        },
        "type": "object",
        "required": [
          "checkpoint_id"
        ],
        "title": "ThreadCheckpoint",
        "description": "Structured identifier for a thread checkpoint, ie. an entry in the thread's history."
      },
      "ThreadState": {
        "properties": {
          "checkpoint": {
            "$ref": "#/components/schemas/ThreadCheckpoint",
            "title": "Checkpoint",
            "description": "The identifier for this checkpoint."
          },
          "values": {
            "title": "Values",
            "description": "The current state of the thread.",
            "$ref": "#/components/schemas/ThreadStateSchema"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            },
            "title": "Messages",
            "description": "The current messages of the thread. If messages are contained in Thread.values, implementations should remove them from values when returning messages. When this key isn't present it means the thread/agent doesn't support messages."
          },
          "metadata": {
            "type": "object",
            "title": "Metadata",
            "description": "The checkpoint metadata."
          }
        },
        "type": "object",
        "required": [
          "checkpoint",
          "values"
        ],
        "title": "ThreadState"
      },
      "ThreadCreate": {
        "type": "object",
        "title": "Thread",
        "description": "Detail of an empty thread to be created.",
        "properties": {
          "thread_id": {
            "type": "string",
            "format": "uuid",
            "title": "Thread Id",
            "description": "The ID of the thread. If not provided, a random UUID will be generated."
          },
          "metadata": {
            "type": "object",
            "title": "Metadata",
            "description": "Free form metadata for this thread"
          },
          "if_exists": {
            "type": "string",
            "enum": [
              "raise",
              "do_nothing"
            ],
            "title": "If Exists",
            "description": "How to handle duplicate creation. Must be either 'raise' (raise error if duplicate), or 'do_nothing' (return existing thread).",
            "default": "raise"
          }
        }
      },
      "ThreadPatch": {
        "properties": {
          "checkpoint": {
            "$ref": "#/components/schemas/ThreadCheckpoint",
            "title": "Checkpoint",
            "description": "The identifier of the checkpoint to branch from. Ignored for metadata-only patches. If not provided, defaults to the latest checkpoint."
          },
          "metadata": {
            "type": "object",
            "title": "Metadata",
            "description": "Metadata to merge with existing thread metadata."
          },
          "values": {
            "title": "Values",
            "description": "The current state of the thread.",
            "$ref": "#/components/schemas/ThreadStateSchema"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            },
            "title": "Messages",
            "description": "The current Messages of the thread. If messages are contained in Thread.values, implementations should remove them from values when returning messages. When this key isn't present it means the thread/agent doesn't support messages."
          }
        },
        "type": "object",
        "title": "ThreadPatch",
        "description": "Payload for updating a thread."
      },
      "Message": {
        "type": "object",
        "properties": {
          "role": {
            "type": "string",
            "title": "Role",
            "description": "The role of the message."
          },
          "content": {
            "title": "Content",
            "description": "The content of the message.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "array",
                "items": {
                  "anyOf": [
                    {
                      "type": "object",
                      "properties": {
                        "text": {
                          "type": "string"
                        },
                        "type": {
                          "const": "text"
                        },
                        "metadata": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "text",
                        "type"
                      ],
                      "title": "MessageTextBlock"
                    },
                    {
                      "type": "object",
                      "properties": {
                        "type": {
                          "type": "string"
                        },
                        "metadata": {
                          "type": "object"
                        }
                      },
                      "required": [
                        "type"
                      ],
                      "title": "MessageAnyBlock"
                    }
                  ]
                }
              }
            ]
          },
          "id": {
            "type": "string",
            "title": "Id",
            "description": "The ID of the message."
          },
          "metadata": {
            "type": "object",
            "title": "Metadata",
            "description": "The metadata of the message."
          }
        },
        "required": [
          "role",
          "content"
        ]
      },
      "ErrorResponse": {
        "type": "string",
        "title": "ErrorResponse",
        "description": "Error message returned from the server"
      },
      "RunCreate": {
        "properties": {
          "agent_id": {
            "type": "string",
            "title": "Agent Id",
            "description": "The agent ID to run. If not provided will use the default agent for this service."
          },
          "input": {
            "$ref": "#/components/schemas/InputSchema"
          },
          "metadata": {
            "type": "object",
            "title": "Metadata",
            "description": "Metadata to assign to the run."
          },
          "config": {
            "properties": {
              "tags": {
                "items": {
                  "type": "string"
                },
                "type": "array",
                "title": "Tags"
              },
              "recursion_limit": {
                "type": "integer",
                "title": "Recursion Limit"
              },
              "configurable": {
                "$ref": "#/components/schemas/ConfigSchema"
              }
            },
            "type": "object",
            "title": "Config",
            "description": "The configuration for the agent."
          },
          "webhook": {
            "type": "string",
            "format": "uri",
            "maxLength": 65536,
            "minLength": 1,
            "title": "Status change webhook",
            "description": "Webhook to call upon change of run status. This is a url that accepts a POST containing the `Run` object as body. See Callbacks definition."
          },
          "stream_mode": {
            "anyOf": [
              {
                "items": {
                  "$ref": "#/components/schemas/StreamingMode"
                },
                "type": "array"
              },
              {
                "$ref": "#/components/schemas/StreamingMode"
              },
              { "type": "null" }
            ],
            "title": "Stream Mode",
            "description": "If populated, indicates that the client requests to stream results with the specified streaming mode(s). The requested streaming mode(s) must be one or more of those supported by the agent as declared in agent ACP descriptor  under `specs.capabilities`",
            "default": null
          },
          "on_disconnect": {
            "type": "string",
            "enum": [
              "cancel",
              "continue"
            ],
            "title": "On Disconnect",
            "description": "The disconnect mode to use. Must be one of 'cancel' or 'continue'.",
            "default": "cancel"
          },
          "multitask_strategy": {
            "type": "string",
            "enum": [
              "reject",
              "rollback",
              "interrupt",
              "enqueue"
            ],
            "title": "Multitask Strategy",
            "description": "Multitask strategy to use. Must be one of 'reject', 'interrupt', 'rollback', or 'enqueue'.",
            "default": "reject"
          },
          "after_seconds": {
            "type": "integer",
            "title": "After Seconds",
            "description": "The number of seconds to wait before starting the run. Use to schedule future runs."
          }
        },
        "type": "object",
        "required": [],
        "title": "RunCreateStateful",
        "description": "Payload for creating a run."
      },
      "StreamingMode": {
        "type": "string",
        "enum": [
          "values",
          "custom"
        ]
      },
      "RunStatus": {
        "type": "string",
        "enum": [
          "pending",
          "error",
          "success",
          "timeout",
          "interrupted"
        ]
      },
      "ThreadStatus": {
        "type": "string",
        "enum": [
          "idle",
          "busy",
          "interrupted",
          "error"
        ]
      },
      "RunSearchRequest": {
        "properties": {
          "agent_id": {
            "type": "string",
            "format": "uuid",
            "title": "Agent Id",
            "description": "Matches all the Runs associated with the specified Agent ID."
          },
          "status": {
            "$ref": "#/components/schemas/RunStatus",
            "title": "Status",
            "description": "Matches all the Runs associated with the specified status. One of 'pending', 'error', 'success', 'timeout', 'interrupted'."
          },
          "metadata": {
            "type": "object",
            "title": "Metadata Filter",
            "description": "Matches all threads for which metadata has  keys and values equal to those specified in this object."
          },
          "limit": {
            "type": "integer",
            "title": "Limit",
            "description": "Maximum number to return.",
            "default": 10,
            "minimum": 1,
            "maximum": 1000
          },
          "offset": {
            "type": "integer",
            "title": "Offset",
            "description": "Offset to start from.",
            "default": 0,
            "minimum": 0
          }
        },
        "type": "object",
        "title": "Run Search Request",
        "description": "Payload for listing runs."
      },
      "RunOutput": {
        "title": "Run Output",
        "description": "Output of a Run. Can be the final result or an interrupt.",
        "oneOf": [
          {
            "$ref": "#/components/schemas/RunResult"
          },
          {
            "$ref": "#/components/schemas/RunInterrupt"
          },
          {
            "$ref": "#/components/schemas/RunError"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "result": "#/components/schemas/RunResult",
            "interrupt": "#/components/schemas/RunInterrupt",
            "error": "#/components/schemas/RunError"
          }
        }
      },
      "RunResult": {
        "title": "Run Result",
        "description": "Final result of a Run.",
        "type": "object",
        "properties": {
          "type": {
            "title": "Output Type",
            "type": "string",
            "enum": [
              "result"
            ]
          },
          "values": {
            "$ref": "#/components/schemas/OutputSchema"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            },
            "title": "Messages",
            "description": "The messages returned by the run."
          }
        },
        "required": [
          "type"
        ]
      },
      "ValueRunResultUpdate": {
        "title": "Value Run Result Update",
        "description": "Partial result provided as value through streaming.",
        "type": "object",
        "properties": {
          "type": {
            "title": "Streaming Output Type",
            "type": "string",
            "enum": [
              "values"
            ]
          },
          "run_id": {
            "type": "string",
            "format": "uuid",
            "title": "Run Id",
            "description": "The ID of the run."
          },
          "status": {
            "title": "Run Status",
            "description": "Status of the Run when this result was generated. This is particurarly useful when this data structure is used for streaming results. As the server can indicate an interrupt or an error condition while streaming the result.",
            "$ref": "#/components/schemas/RunStatus"
          },
          "values": {
            "$ref": "#/components/schemas/OutputSchema"
          },
          "messages": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/Message"
            },
            "title": "Messages",
            "description": "Stream of messages returned by the run."
          }
        },
        "required": [
          "type",
          "run_id",
          "status",
          "values"
        ]
      },
      "RunOutputStream": {
        "type": "object",
        "title": "Run Output Stream Event",
        "description": "Server-sent event containing one agent output event. Actual event type is carried inside the data.",
        "properties": {
          "id": {
            "type": "string",
            "description": "Unique identifier of the event",
            "title": "Event ID"
          },
          "event": {
            "type": "string",
            "enum": [
              "agent_event"
            ],
            "description": "Event type. This is the constant string `agent_event` to be compatible with SSE spec. The actual type differentiation is done in the event itself."
          },
          "data": {
            "title": "Stream Event Payload",
            "description": "A serialized JSON data structure carried in the SSE event data field. The event can carry either a full `ValueRunResultUpdate`, if streaming mode is `values` or an `CustomRunResultUpdate` if streaming mode is `custom`",
            "oneOf": [
              {
                "$ref": "#/components/schemas/ValueRunResultUpdate"
              },
              {
                "$ref": "#/components/schemas/CustomRunResultUpdate"
              }
            ],
            "discriminator": {
              "propertyName": "type",
              "mapping": {
                "values": "#/components/schemas/ValueRunResultUpdate",
                "custom": "#/components/schemas/CustomRunResultUpdate"
              }
            }
          }
        },
        "required": [
          "id",
          "event",
          "data"
        ]
      },
      "CustomRunResultUpdate": {
        "title": "Custom Run Result Update",
        "description": "Object holding a custom defined update of the agent result during streaming.",
        "type": "object",
        "properties": {
          "type": {
            "title": "Streaming Output Type",
            "type": "string",
            "enum": [
              "custom"
            ]
          },
          "run_id": {
            "type": "string",
            "format": "uuid",
            "title": "Run Id",
            "description": "The ID of the run."
          },
          "status": {
            "title": "Run Status",
            "description": "Status of the Run when this result was generated",
            "$ref": "#/components/schemas/RunStatus"
          },
          "update": {
            "$ref": "#/components/schemas/StreamUpdateSchema"
          }
        },
        "required": [
          "type",
          "status",
          "update"
        ]
      },
      "RunError": {
        "title": "Run Error",
        "description": "Run terminated with an error",
        "type": "object",
        "properties": {
          "type": {
            "title": "Output Type",
            "type": "string",
            "enum": [
              "error"
            ]
          },
          "run_id": {
            "type": "string",
            "format": "uuid",
            "title": "Run Id",
            "description": "The ID of the run."
          },
          "errcode": {
            "type": "integer",
            "title": "Error Code",
            "description": "code of the error"
          },
          "description": {
            "type": "string",
            "title": "Error Description",
            "description": "description of the error"
          }
        },
        "required": [
          "type",
          "run_id",
          "errcode",
          "description"
        ]
      },
      "RunInterrupt": {
        "title": "Run Interrupt",
        "description": "Interrupt occurred during a Run",
        "type": "object",
        "properties": {
          "type": {
            "title": "Output Type",
            "type": "string",
            "enum": [
              "interrupt"
            ]
          },
          "interrupt": {
            "$ref": "#/components/schemas/InterruptPayloadSchema"
          }
        },
        "required": [
          "type",
          "interrupt"
        ]
      },
      "InputSchema": {
        "type": "object",
        "title": "Input Schema",
        "description": "The input to the agent. The schema is described in agent ACP descriptor under 'spec.thread_state'.'input'."
      },
      "OutputSchema": {
        "type": "object",
        "title": "Output Schema",
        "description": "The output of the agent. The schema is described in agent ACP descriptor under 'spec.output'."
      },
      "ConfigSchema": {
        "type": "object",
        "title": "Config",
        "description": "The configuration for this agent. The schema is described in agent ACP descriptor under 'spec.config'. If missing, default values are used."
      },
      "ThreadStateSchema": {
        "type": "object",
        "title": "Thread State Schema",
        "description": "The thread state. The schema is described in agent ACP descriptor under 'spec.thread_state'."
      },
      "StreamUpdateSchema": {
        "type": "object",
        "title": "Stream Update Schema",
        "description": "An update in the SSE event streaming where streaming mode is set to custom. The schema is described in agent ACP descriptor under 'spec.custom_streaming_update'."
      },
      "InterruptPayloadSchema": {
        "type": "object",
        "title": "Interrupt Payload",
        "description": "This schema describes the interrupt payload. Actual schema describes a polimorphic object, which means a schema structured with `oneOf` and `discriminator`. The discriminator is the `interrupt_type`, while the schemas will be the ones defined in the agent spec under `interrupts`/`interrupt_payload` For example:          oneOf:\n  - $ref: '#/components/schemas/ApprovalInterruptPayload'\n  - $ref: '#/components/schemas/QuestionInterruptPayload'\ndiscriminator:\n  propertyName: interruput_type\n  mapping:\n    approval: '#/components/schemas/ApprovalInterruptPayload'\n    question: '#/components/schemas/QuestionInterruptPayload'"
      },
      "ResumePayloadSchema": {
        "type": "object",
        "title": "Resume Payload Schema",
        "description": "This schema describes the resume payload after an interrupt. Actual schema describes a polimorphic object, which means a schema structured with `oneOf` and `discriminator`. The discriminator is the `interrupt_type`, while the schemas will be those defined in the agent spec under `interrupts`/`resume_payload` For example:          oneOf:\n  - $ref: '#/components/schemas/ApprovalResumePayload'\n  - $ref: '#/components/schemas/QuestionResumePayload'\ndiscriminator:\n  propertyName: interrupt_type\n  mapping:\n    approval: '#/components/schemas/ApprovalResumePayload'\n    question: '#/components/schemas/QuestionResumePayload'"
      }
    }
  }
}