From 23858df775d0a617c6418eed28f1b68c9bf9ed5c Mon Sep 17 00:00:00 2001 From: Max Parke Date: Wed, 17 Jun 2026 01:39:55 -0400 Subject: [PATCH 1/5] docs: drop stale keep_files / dashboard-config comments (#401) Co-authored-by: Claude Opus 4.8 (1M context) --- adk/README.md | 2 +- adk/pyproject.toml | 3 --- pyproject.toml | 5 ----- 3 files changed, 1 insertion(+), 9 deletions(-) diff --git a/adk/README.md b/adk/README.md index 958cf9368..73a961dd1 100644 --- a/adk/README.md +++ b/adk/README.md @@ -29,4 +29,4 @@ The two packages contribute disjoint files to the `agentex.*` namespace — `age ## Repo layout -This package is hand-authored and lives at `adk/` inside [scaleapi/scale-agentex-python](https://github.com/scaleapi/scale-agentex-python). The Stainless generator preserves `adk/**` via `keep_files` so its codegen never touches anything here. The sibling `agentex-client` package lives at the repo root and IS Stainless-generated. +This package is hand-authored and lives at `adk/` inside [scaleapi/scale-agentex-python](https://github.com/scaleapi/scale-agentex-python). Stainless codegen never touches `adk/**` — it's outside the generated surface. The sibling `agentex-client` package lives at the repo root and IS Stainless-generated. diff --git a/adk/pyproject.toml b/adk/pyproject.toml index 418e10864..33132a736 100644 --- a/adk/pyproject.toml +++ b/adk/pyproject.toml @@ -3,9 +3,6 @@ # `agentex/lib/*` to the agentex.* namespace; the REST client surface # (agentex/{__init__.py, _*.py, types/, resources/}) ships from the slim # sibling package `agentex-client` which is pinned as a runtime dep. -# -# This entire `adk/` directory must be preserved across Stainless codegen -# via `keep_files: ["adk/**"]` in the Stainless dashboard config. name = "agentex-sdk" version = "0.13.0" description = "Agent Development Kit (ADK) overlay for the Agentex API — FastACP server, Temporal workflows, LLM provider integrations, observability" diff --git a/pyproject.toml b/pyproject.toml index f9079e08a..09a61f048 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -2,11 +2,6 @@ # This is the Stainless-generated REST client. The hand-authored ADK # overlay (formerly `src/agentex/lib/*`) now lives in `adk/` and ships # as the sibling `agentex-sdk` package — see `adk/pyproject.toml`. -# -# Stainless dashboard config must: -# - Rename `package_name` from `agentex-sdk` to `agentex-client` -# - Reduce the dep list to the 6 bare-client deps below -# - Add `adk/**` to `keep_files` so the ADK overlay persists across codegen name = "agentex-client" version = "0.13.0" description = "The official Python REST client for the Agentex API" From f59f26d4402f01318cf34d57820e121d97719986 Mon Sep 17 00:00:00 2001 From: Max Parke Date: Wed, 17 Jun 2026 12:41:16 -0400 Subject: [PATCH 2/5] fix(adk): re-send task_id/agent_id in state updates for backend compatibility (#405) Co-authored-by: Claude Opus 4.8 --- src/agentex/lib/core/services/adk/state.py | 3 + tests/lib/adk/test_state_service.py | 69 ++++++++++++++++++++++ 2 files changed, 72 insertions(+) create mode 100644 tests/lib/adk/test_state_service.py diff --git a/src/agentex/lib/core/services/adk/state.py b/src/agentex/lib/core/services/adk/state.py index 88a9b71b3..93012b933 100644 --- a/src/agentex/lib/core/services/adk/state.py +++ b/src/agentex/lib/core/services/adk/state.py @@ -98,9 +98,12 @@ async def update_state( "state": state, }, ) as span: + # Send task_id/agent_id in the body for backends predating + # scale-agentex#278, which still require them (newer ones ignore them). state_model = await self._agentex_client.states.update( state_id=state_id, state=state, + extra_body={"task_id": task_id, "agent_id": agent_id}, ) if span: span.output = state_model.model_dump() diff --git a/tests/lib/adk/test_state_service.py b/tests/lib/adk/test_state_service.py new file mode 100644 index 000000000..43b53ff39 --- /dev/null +++ b/tests/lib/adk/test_state_service.py @@ -0,0 +1,69 @@ +"""Tests for StateService forwarding task_id/agent_id to the SDK client. + +Regression guard for the 0.13.0 incident: the generated client dropped +task_id/agent_id from states.update(), so the ADK stopped sending them in the +body and every state write 422'd against backends predating scale-agentex#278. +""" + +from __future__ import annotations + +from datetime import datetime, timezone +from unittest.mock import Mock, AsyncMock + +from agentex.types.state import State +from agentex.lib.core.services.adk.state import StateService + +_TS = datetime(2026, 5, 13, 18, 30, 0, tzinfo=timezone.utc) + + +def _make_state() -> State: + return State( + id="s1", + agent_id="a1", + task_id="t1", + state={"k": "v"}, + created_at=_TS, + ) + + +def _mock_span(): + span = Mock() + span.output = None + + async def __aenter__(_self): + return span + + async def __aexit__(_self, *args): + return None + + span.__aenter__ = __aenter__ + span.__aexit__ = __aexit__ + return span + + +def _make_service() -> tuple[AsyncMock, StateService]: + client = AsyncMock() + tracer = Mock() + trace = Mock() + trace.span.return_value = _mock_span() + tracer.trace.return_value = trace + return client, StateService(agentex_client=client, tracer=tracer) + + +class TestUpdateStateSendsParentIdentifiers: + async def test_task_id_and_agent_id_sent_in_body(self) -> None: + client, svc = _make_service() + client.states.update.return_value = _make_state() + + await svc.update_state( + state_id="s1", + task_id="t1", + agent_id="a1", + state={"k": "v"}, + ) + + kwargs = client.states.update.call_args.kwargs + assert kwargs["state_id"] == "s1" + # task_id/agent_id must ride in extra_body — the generated client dropped + # them from the typed signature, but old backends still require them. + assert kwargs["extra_body"] == {"task_id": "t1", "agent_id": "a1"} From 862c53993204d72b4710499c3deb9cdaa763d987 Mon Sep 17 00:00:00 2001 From: Max Parke Date: Wed, 17 Jun 2026 13:01:00 -0400 Subject: [PATCH 3/5] test(compat): cross-version request-compatibility against supported server contracts (#407) Co-authored-by: Claude Opus 4.8 --- tests/compat/__init__.py | 0 tests/compat/refresh_specs.py | 34 + tests/compat/server_specs/current.yaml | 6741 +++++++++++++++++ tests/compat/server_specs/manifest.json | 19 + tests/compat/server_specs/min-supported.yaml | 6761 ++++++++++++++++++ tests/compat/test_request_compat.py | 129 + 6 files changed, 13684 insertions(+) create mode 100644 tests/compat/__init__.py create mode 100644 tests/compat/refresh_specs.py create mode 100644 tests/compat/server_specs/current.yaml create mode 100644 tests/compat/server_specs/manifest.json create mode 100644 tests/compat/server_specs/min-supported.yaml create mode 100644 tests/compat/test_request_compat.py diff --git a/tests/compat/__init__.py b/tests/compat/__init__.py new file mode 100644 index 000000000..e69de29bb diff --git a/tests/compat/refresh_specs.py b/tests/compat/refresh_specs.py new file mode 100644 index 000000000..396d4afa5 --- /dev/null +++ b/tests/compat/refresh_specs.py @@ -0,0 +1,34 @@ +"""Re-vendor the server OpenAPI specs at the SHAs pinned in manifest.json. +Usage: `python tests/compat/refresh_specs.py` (needs `gh` auth for the source repo).""" + +from __future__ import annotations + +import json +import subprocess +from pathlib import Path + +_DIR = Path(__file__).parent / "server_specs" + + +def main() -> None: + manifest = json.loads((_DIR / "manifest.json").read_text()) + repo, path = manifest["source_repo"], manifest["source_path"] + for entry in manifest["specs"]: + content = subprocess.run( + [ + "gh", + "api", + f"repos/{repo}/contents/{path}?ref={entry['sha']}", + "-H", + "Accept: application/vnd.github.raw", + ], + check=True, + capture_output=True, + text=True, + ).stdout + (_DIR / entry["file"]).write_text(content) + print(f"wrote {entry['file']} from {repo}@{entry['sha'][:12]}") + + +if __name__ == "__main__": + main() diff --git a/tests/compat/server_specs/current.yaml b/tests/compat/server_specs/current.yaml new file mode 100644 index 000000000..b122020e4 --- /dev/null +++ b/tests/compat/server_specs/current.yaml @@ -0,0 +1,6741 @@ +openapi: 3.1.0 +info: + title: Agentex API + version: 0.1.0 +paths: + /agents/{agent_id}: + get: + tags: + - Agents + summary: Get Agent by ID + description: Get an agent by its unique ID. + operationId: get_agent_by_id_agents__agent_id__get + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Agents + summary: Delete Agent by ID + description: Delete an agent by its unique ID. + operationId: delete_agent_by_id_agents__agent_id__delete + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/name/{agent_name}: + get: + tags: + - Agents + summary: Get Agent by Name + description: Get an agent by its unique name. + operationId: get_agent_by_name_agents_name__agent_name__get + parameters: + - name: agent_name + in: path + required: true + schema: + type: string + title: Agent Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Agents + summary: Delete Agent by Name + description: Delete an agent by its unique name. + operationId: delete_agent_by_name_agents_name__agent_name__delete + parameters: + - name: agent_name + in: path + required: true + schema: + type: string + title: Agent Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents: + get: + tags: + - Agents + summary: List Agents + description: List all registered agents, optionally filtered by query parameters. + operationId: list_agents_agents_get + parameters: + - name: task_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Task ID + title: Task Id + description: Task ID + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + description: Limit + default: 50 + title: Limit + description: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + description: Page number + default: 1 + title: Page Number + description: Page number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Field to order by + title: Order By + description: Field to order by + - name: order_direction + in: query + required: false + schema: + type: string + description: Order direction (asc or desc) + default: desc + title: Order Direction + description: Order direction (asc or desc) + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Agent' + title: Response List Agents Agents Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/register: + post: + tags: + - Agents + summary: Register Agent + description: Register a new agent or update an existing one. + operationId: register_agent_agents_register_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterAgentRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterAgentResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/register-build: + post: + tags: + - Agents + summary: Register Build + description: Register an agent at build time, before it is deployed, so it can + be permissioned and shared prior to deploy. Idempotent by name. + operationId: register_build_agents_register_build_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterBuildRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/forward/name/{agent_name}/{path}: + get: + tags: + - Agents + summary: Forward GET request to agent by name + description: Forward a GET request to an agent by its name. + operationId: forward_get_request_to_agent_agents_forward_name__agent_name___path__get + parameters: + - name: agent_name + in: path + required: true + schema: + type: string + title: Agent Name + - name: path + in: path + required: true + schema: + type: string + title: Path + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + post: + tags: + - Agents + summary: Forward POST request to agent by name + description: Forward a POST request to an agent by its name. + operationId: forward_post_request_to_agent_agents_forward_name__agent_name___path__post + parameters: + - name: agent_name + in: path + required: true + schema: + type: string + title: Agent Name + - name: path + in: path + required: true + schema: + type: string + title: Path + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/rpc: + post: + tags: + - Agents + summary: Handle Agent RPC by ID + description: Handle JSON-RPC requests for an agent by its unique ID. + operationId: handle_agent_rpc_by_id_agents__agent_id__rpc_post + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/name/{agent_name}/rpc: + post: + tags: + - Agents + summary: Handle Agent RPC by Name + description: Handle JSON-RPC requests for an agent by its unique name. + operationId: handle_agent_rpc_by_name_agents_name__agent_name__rpc_post + parameters: + - name: agent_name + in: path + required: true + schema: + type: string + title: Agent Name + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}: + get: + tags: + - Tasks + summary: Get Task by ID + description: Get a task by its unique ID. + operationId: get_task_tasks__task_id__get + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + - name: relationships + in: query + required: false + schema: + type: array + items: + $ref: '#/components/schemas/TaskRelationships' + title: Relationships + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TaskResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Tasks + summary: Delete Task by ID + description: Delete a task by its unique ID. + operationId: delete_task_tasks__task_id__delete + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + tags: + - Tasks + summary: Update Task by ID + description: Update mutable fields for a task by its unique ID. + operationId: update_task_tasks__task_id__put + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateTaskRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/name/{task_name}: + get: + tags: + - Tasks + summary: Get Task by Name + description: Get a task by its unique name. + operationId: get_task_by_name_tasks_name__task_name__get + parameters: + - name: task_name + in: path + required: true + schema: + type: string + title: Task Name + - name: relationships + in: query + required: false + schema: + type: array + items: + $ref: '#/components/schemas/TaskRelationships' + title: Relationships + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TaskResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Tasks + summary: Delete Task by Name + description: Delete a task by its unique name. + operationId: delete_task_by_name_tasks_name__task_name__delete + parameters: + - name: task_name + in: path + required: true + schema: + type: string + title: Task Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + tags: + - Tasks + summary: Update Task by Name + description: Update mutable fields for a task by its unique Name. + operationId: update_task_by_name_tasks_name__task_name__put + parameters: + - name: task_name + in: path + required: true + schema: + type: string + title: Task Name + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateTaskRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks: + get: + tags: + - Tasks + summary: List Tasks + description: List all tasks. + operationId: list_tasks_tasks_get + parameters: + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: agent_name + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Name + - name: status + in: query + required: false + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatus' + - type: 'null' + description: Filter tasks by status (e.g. RUNNING, COMPLETED). + title: Status + description: Filter tasks by status (e.g. RUNNING, COMPLETED). + - name: task_metadata + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: 'JSON-encoded object used to filter tasks via JSONB containment. + Example: {"created_by_user_id": "abc-123"}.' + title: Task Metadata + description: 'JSON-encoded object used to filter tasks via JSONB containment. + Example: {"created_by_user_id": "abc-123"}.' + - name: limit + in: query + required: false + schema: + type: integer + default: 50 + title: Limit + - name: page_number + in: query + required: false + schema: + type: integer + default: 1 + title: Page Number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Order By + - name: order_direction + in: query + required: false + schema: + type: string + default: desc + title: Order Direction + - name: relationships + in: query + required: false + schema: + type: array + items: + $ref: '#/components/schemas/TaskRelationships' + title: Relationships + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/TaskResponse' + title: Response List Tasks Tasks Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/complete: + post: + tags: + - Tasks + summary: Complete Task + description: Mark a running task as completed. + operationId: complete_task_tasks__task_id__complete_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatusReasonRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/fail: + post: + tags: + - Tasks + summary: Fail Task + description: Mark a running task as failed. + operationId: fail_task_tasks__task_id__fail_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatusReasonRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/cancel: + post: + tags: + - Tasks + summary: Cancel Task + description: Mark a running task as canceled. + operationId: cancel_task_tasks__task_id__cancel_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatusReasonRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/terminate: + post: + tags: + - Tasks + summary: Terminate Task + description: Mark a running task as terminated. + operationId: terminate_task_tasks__task_id__terminate_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatusReasonRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/timeout: + post: + tags: + - Tasks + summary: Timeout Task + description: Mark a running task as timed out. + operationId: timeout_task_tasks__task_id__timeout_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatusReasonRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/stream: + get: + tags: + - Tasks + summary: Stream Task Events by ID + description: Stream events for a task by its unique ID. + operationId: stream_task_events_tasks__task_id__stream_get + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/name/{task_name}/stream: + get: + tags: + - Tasks + summary: Stream Task Events by Name + description: Stream events for a task by its unique name. + operationId: stream_task_events_by_name_tasks_name__task_name__stream_get + parameters: + - name: task_name + in: path + required: true + schema: + type: string + title: Task Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/query/{query_name}: + get: + tags: + - Tasks + summary: Query Task Workflow + description: Query a Temporal workflow associated with a task for its current + state. + operationId: query_task_workflow_tasks__task_id__query__query_name__get + parameters: + - name: query_name + in: path + required: true + schema: + type: string + title: Query Name + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: object + additionalProperties: true + title: Response Query Task Workflow Tasks Task Id Query Query Name Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /messages/batch: + put: + tags: + - Messages + summary: Batch Update Messages + operationId: batch_update_messages_messages_batch_put + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BatchUpdateTaskMessagesRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + items: + $ref: '#/components/schemas/TaskMessage' + type: array + title: Response Batch Update Messages Messages Batch Put + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + post: + tags: + - Messages + summary: Batch Create Messages + operationId: batch_create_messages_messages_batch_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BatchCreateTaskMessagesRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + items: + $ref: '#/components/schemas/TaskMessage' + type: array + title: Response Batch Create Messages Messages Batch Post + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /messages: + post: + tags: + - Messages + summary: Create Message + operationId: create_message_messages_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateTaskMessageRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TaskMessage' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Messages + summary: List Messages + description: 'List messages for a task with offset-based pagination. + + + For cursor-based pagination with infinite scroll support, use /messages/paginated.' + operationId: list_messages_messages_get + parameters: + - name: limit + in: query + required: false + schema: + type: integer + default: 50 + title: Limit + - name: page_number + in: query + required: false + schema: + type: integer + default: 1 + title: Page Number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Order By + - name: order_direction + in: query + required: false + schema: + type: string + default: desc + title: Order Direction + - name: filters + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: "JSON-encoded array of TaskMessageEntityFilter objects.\n\n\ + Schema: {\n \"$defs\": {\n \"DataContentEntityOptional\": {\n \ + \ \"properties\": {\n \"type\": {\n \"anyOf\": [\n \ + \ {\n \"const\": \"data\",\n \"type\"\ + : \"string\"\n },\n {\n \"type\": \"\ + null\"\n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The type of the message, in this case `data`.\"\ + ,\n \"title\": \"Type\"\n },\n \"author\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"data\"\ + : {\n \"anyOf\": [\n {\n \"additionalProperties\"\ + : true,\n \"type\": \"object\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The contents\ + \ of the data message.\",\n \"title\": \"Data\"\n }\n\ + \ },\n \"title\": \"DataContentEntityOptional\",\n \"type\"\ + : \"object\"\n },\n \"FileAttachmentEntity\": {\n \"description\"\ + : \"Represents a file attachment in messages.\",\n \"properties\"\ + : {\n \"file_id\": {\n \"description\": \"The unique ID\ + \ of the attached file\",\n \"title\": \"File Id\",\n \ + \ \"type\": \"string\"\n },\n \"name\": {\n \"\ + description\": \"The name of the file\",\n \"title\": \"Name\"\ + ,\n \"type\": \"string\"\n },\n \"size\": {\n \ + \ \"description\": \"The size of the file in bytes\",\n \ + \ \"title\": \"Size\",\n \"type\": \"integer\"\n },\n\ + \ \"type\": {\n \"description\": \"The MIME type or content\ + \ type of the file\",\n \"title\": \"Type\",\n \"type\"\ + : \"string\"\n }\n },\n \"required\": [\n \"file_id\"\ + ,\n \"name\",\n \"size\",\n \"type\"\n ],\n\ + \ \"title\": \"FileAttachmentEntity\",\n \"type\": \"object\"\ + \n },\n \"MessageAuthor\": {\n \"enum\": [\n \"user\"\ + ,\n \"agent\"\n ],\n \"title\": \"MessageAuthor\",\n\ + \ \"type\": \"string\"\n },\n \"MessageStyle\": {\n \"\ + enum\": [\n \"static\",\n \"active\"\n ],\n \"\ + title\": \"MessageStyle\",\n \"type\": \"string\"\n },\n \"\ + ReasoningContentEntityOptional\": {\n \"properties\": {\n \ + \ \"type\": {\n \"anyOf\": [\n {\n \"\ + const\": \"reasoning\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `reasoning`.\",\n \"\ + title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"summary\"\ + : {\n \"anyOf\": [\n {\n \"items\": {\n\ + \ \"type\": \"string\"\n },\n \ + \ \"type\": \"array\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"A list of short reasoning summaries\"\ + ,\n \"title\": \"Summary\"\n },\n \"content\":\ + \ {\n \"anyOf\": [\n {\n \"items\": {\n\ + \ \"type\": \"string\"\n },\n \ + \ \"type\": \"array\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"The reasoning content or chain-of-thought\ + \ text\",\n \"title\": \"Content\"\n }\n },\n \ + \ \"title\": \"ReasoningContentEntityOptional\",\n \"type\": \"\ + object\"\n },\n \"TextContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"text\",\n \"type\": \"string\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The type of the message, in this case `text`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"format\"\ + : {\n \"anyOf\": [\n {\n \"$ref\": \"\ + #/$defs/TextFormat\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"The format of the message. This\ + \ is used by the client to determine how to display the message.\"\n \ + \ },\n \"content\": {\n \"anyOf\": [\n \ + \ {\n \"type\": \"string\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The contents\ + \ of the text message.\",\n \"title\": \"Content\"\n },\n\ + \ \"attachments\": {\n \"anyOf\": [\n {\n \ + \ \"items\": {\n \"$ref\": \"#/$defs/FileAttachmentEntity\"\ + \n },\n \"type\": \"array\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + Optional list of file attachments with structured metadata.\",\n \ + \ \"title\": \"Attachments\"\n }\n },\n \"title\"\ + : \"TextContentEntityOptional\",\n \"type\": \"object\"\n },\n\ + \ \"TextFormat\": {\n \"enum\": [\n \"markdown\",\n \ + \ \"plain\",\n \"code\"\n ],\n \"title\": \"TextFormat\"\ + ,\n \"type\": \"string\"\n },\n \"ToolRequestContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\"\ + : [\n {\n \"const\": \"tool_request\",\n \ + \ \"type\": \"string\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The type of the message,\ + \ in this case `tool_request`.\",\n \"title\": \"Type\"\n \ + \ },\n \"author\": {\n \"anyOf\": [\n {\n\ + \ \"$ref\": \"#/$defs/MessageAuthor\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"tool_call_id\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The ID of the tool call that is being requested.\"\ + ,\n \"title\": \"Tool Call Id\"\n },\n \"name\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The name of the tool that is being requested.\"\ + ,\n \"title\": \"Name\"\n },\n \"arguments\": {\n\ + \ \"anyOf\": [\n {\n \"additionalProperties\"\ + : true,\n \"type\": \"object\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The arguments\ + \ to the tool.\",\n \"title\": \"Arguments\"\n }\n \ + \ },\n \"title\": \"ToolRequestContentEntityOptional\",\n \ + \ \"type\": \"object\"\n },\n \"ToolResponseContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\"\ + : [\n {\n \"const\": \"tool_response\",\n \ + \ \"type\": \"string\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The type of the message,\ + \ in this case `tool_response`.\",\n \"title\": \"Type\"\n \ + \ },\n \"author\": {\n \"anyOf\": [\n \ + \ {\n \"$ref\": \"#/$defs/MessageAuthor\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"tool_call_id\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The ID of the tool call that is being responded\ + \ to.\",\n \"title\": \"Tool Call Id\"\n },\n \"\ + name\": {\n \"anyOf\": [\n {\n \"type\"\ + : \"string\"\n },\n {\n \"type\": \"\ + null\"\n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The name of the tool that is being responded\ + \ to.\",\n \"title\": \"Name\"\n },\n \"content\"\ + : {\n \"anyOf\": [\n {},\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"default\"\ + : null,\n \"description\": \"The result of the tool.\",\n \ + \ \"title\": \"Content\"\n }\n },\n \"title\":\ + \ \"ToolResponseContentEntityOptional\",\n \"type\": \"object\"\n\ + \ }\n },\n \"description\": \"Filter model for TaskMessage - all\ + \ fields optional for flexible filtering.\\n\\nThe `exclude` field determines\ + \ whether this filter is inclusionary or exclusionary.\\nWhen multiple\ + \ filters are provided:\\n- Inclusionary filters (exclude=False) are OR'd\ + \ together\\n- Exclusionary filters (exclude=True) are OR'd together and\ + \ negated with $nor\\n- The two groups are AND'd: (include1 OR include2)\ + \ AND NOT (exclude1 OR exclude2)\",\n \"properties\": {\n \"content\"\ + : {\n \"anyOf\": [\n {\n \"$ref\": \"#/$defs/ToolRequestContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/DataContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/TextContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ToolResponseContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ReasoningContentEntityOptional\"\ + \n },\n {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Filter by message\ + \ content\",\n \"title\": \"Content\"\n },\n \"streaming_status\"\ + : {\n \"anyOf\": [\n {\n \"enum\": [\n \ + \ \"IN_PROGRESS\",\n \"DONE\"\n ],\n \"\ + type\": \"string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \"description\"\ + : \"Filter by streaming status\",\n \"title\": \"Streaming Status\"\ + \n },\n \"exclude\": {\n \"default\": false,\n \"description\"\ + : \"If true, this filter excludes matching messages\",\n \"title\"\ + : \"Exclude\",\n \"type\": \"boolean\"\n }\n },\n \"title\"\ + : \"TaskMessageEntityFilter\",\n \"type\": \"object\"\n}\n\nEach filter\ + \ can include:\n- `content`: Filter by message content (type, author,\ + \ data fields)\n- `streaming_status`: Filter by status (\"IN_PROGRESS\"\ + \ or \"DONE\")\n- `exclude`: If true, excludes matching messages (default:\ + \ false)\n\nMultiple filters are combined: inclusionary filters (exclude=false)\ + \ are OR'd together,\nexclusionary filters (exclude=true) are OR'd and\ + \ negated, then both groups are AND'd.\n" + title: Filters + description: "JSON-encoded array of TaskMessageEntityFilter objects.\n\nSchema:\ + \ {\n \"$defs\": {\n \"DataContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"data\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `data`.\",\n \"title\"\ + : \"Type\"\n },\n \"author\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageAuthor\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"data\": {\n \ + \ \"anyOf\": [\n {\n \"additionalProperties\": true,\n\ + \ \"type\": \"object\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The contents of the data\ + \ message.\",\n \"title\": \"Data\"\n }\n },\n \ + \ \"title\": \"DataContentEntityOptional\",\n \"type\": \"object\"\ + \n },\n \"FileAttachmentEntity\": {\n \"description\": \"Represents\ + \ a file attachment in messages.\",\n \"properties\": {\n \"\ + file_id\": {\n \"description\": \"The unique ID of the attached\ + \ file\",\n \"title\": \"File Id\",\n \"type\": \"string\"\ + \n },\n \"name\": {\n \"description\": \"The name\ + \ of the file\",\n \"title\": \"Name\",\n \"type\": \"\ + string\"\n },\n \"size\": {\n \"description\": \"\ + The size of the file in bytes\",\n \"title\": \"Size\",\n \ + \ \"type\": \"integer\"\n },\n \"type\": {\n \ + \ \"description\": \"The MIME type or content type of the file\",\n \ + \ \"title\": \"Type\",\n \"type\": \"string\"\n }\n\ + \ },\n \"required\": [\n \"file_id\",\n \"name\"\ + ,\n \"size\",\n \"type\"\n ],\n \"title\": \"FileAttachmentEntity\"\ + ,\n \"type\": \"object\"\n },\n \"MessageAuthor\": {\n \"\ + enum\": [\n \"user\",\n \"agent\"\n ],\n \"title\"\ + : \"MessageAuthor\",\n \"type\": \"string\"\n },\n \"MessageStyle\"\ + : {\n \"enum\": [\n \"static\",\n \"active\"\n ],\n\ + \ \"title\": \"MessageStyle\",\n \"type\": \"string\"\n },\n\ + \ \"ReasoningContentEntityOptional\": {\n \"properties\": {\n \ + \ \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"reasoning\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `reasoning`.\",\n \"\ + title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"summary\": {\n \ + \ \"anyOf\": [\n {\n \"items\": {\n \ + \ \"type\": \"string\"\n },\n \"type\":\ + \ \"array\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \"\ + description\": \"A list of short reasoning summaries\",\n \"title\"\ + : \"Summary\"\n },\n \"content\": {\n \"anyOf\":\ + \ [\n {\n \"items\": {\n \"type\"\ + : \"string\"\n },\n \"type\": \"array\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The reasoning content or chain-of-thought text\",\n \"title\"\ + : \"Content\"\n }\n },\n \"title\": \"ReasoningContentEntityOptional\"\ + ,\n \"type\": \"object\"\n },\n \"TextContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\":\ + \ [\n {\n \"const\": \"text\",\n \"\ + type\": \"string\"\n },\n {\n \"type\"\ + : \"null\"\n }\n ],\n \"default\": null,\n\ + \ \"description\": \"The type of the message, in this case `text`.\"\ + ,\n \"title\": \"Type\"\n },\n \"author\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"format\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/TextFormat\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The format of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"content\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The contents of the text message.\",\n \"title\": \"Content\"\ + \n },\n \"attachments\": {\n \"anyOf\": [\n \ + \ {\n \"items\": {\n \"$ref\": \"#/$defs/FileAttachmentEntity\"\ + \n },\n \"type\": \"array\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Optional\ + \ list of file attachments with structured metadata.\",\n \"title\"\ + : \"Attachments\"\n }\n },\n \"title\": \"TextContentEntityOptional\"\ + ,\n \"type\": \"object\"\n },\n \"TextFormat\": {\n \"enum\"\ + : [\n \"markdown\",\n \"plain\",\n \"code\"\n \ + \ ],\n \"title\": \"TextFormat\",\n \"type\": \"string\"\n \ + \ },\n \"ToolRequestContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"tool_request\",\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `tool_request`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"tool_call_id\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The ID of the tool call that is being requested.\",\n \"title\"\ + : \"Tool Call Id\"\n },\n \"name\": {\n \"anyOf\"\ + : [\n {\n \"type\": \"string\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"The\ + \ name of the tool that is being requested.\",\n \"title\": \"\ + Name\"\n },\n \"arguments\": {\n \"anyOf\": [\n \ + \ {\n \"additionalProperties\": true,\n \ + \ \"type\": \"object\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"default\"\ + : null,\n \"description\": \"The arguments to the tool.\",\n \ + \ \"title\": \"Arguments\"\n }\n },\n \"title\"\ + : \"ToolRequestContentEntityOptional\",\n \"type\": \"object\"\n \ + \ },\n \"ToolResponseContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"tool_response\",\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `tool_response`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \"\ + anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"tool_call_id\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The ID of the tool call that is being responded to.\",\n \"\ + title\": \"Tool Call Id\"\n },\n \"name\": {\n \"\ + anyOf\": [\n {\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n }\n\ + \ ],\n \"default\": null,\n \"description\":\ + \ \"The name of the tool that is being responded to.\",\n \"title\"\ + : \"Name\"\n },\n \"content\": {\n \"anyOf\": [\n\ + \ {},\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The result of the tool.\",\n \"title\": \"Content\"\n \ + \ }\n },\n \"title\": \"ToolResponseContentEntityOptional\"\ + ,\n \"type\": \"object\"\n }\n },\n \"description\": \"Filter\ + \ model for TaskMessage - all fields optional for flexible filtering.\\\ + n\\nThe `exclude` field determines whether this filter is inclusionary or\ + \ exclusionary.\\nWhen multiple filters are provided:\\n- Inclusionary filters\ + \ (exclude=False) are OR'd together\\n- Exclusionary filters (exclude=True)\ + \ are OR'd together and negated with $nor\\n- The two groups are AND'd:\ + \ (include1 OR include2) AND NOT (exclude1 OR exclude2)\",\n \"properties\"\ + : {\n \"content\": {\n \"anyOf\": [\n {\n \"$ref\"\ + : \"#/$defs/ToolRequestContentEntityOptional\"\n },\n {\n\ + \ \"$ref\": \"#/$defs/DataContentEntityOptional\"\n },\n\ + \ {\n \"$ref\": \"#/$defs/TextContentEntityOptional\"\n\ + \ },\n {\n \"$ref\": \"#/$defs/ToolResponseContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ReasoningContentEntityOptional\"\ + \n },\n {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Filter by message\ + \ content\",\n \"title\": \"Content\"\n },\n \"streaming_status\"\ + : {\n \"anyOf\": [\n {\n \"enum\": [\n \"\ + IN_PROGRESS\",\n \"DONE\"\n ],\n \"type\":\ + \ \"string\"\n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\": \"Filter\ + \ by streaming status\",\n \"title\": \"Streaming Status\"\n },\n\ + \ \"exclude\": {\n \"default\": false,\n \"description\": \"\ + If true, this filter excludes matching messages\",\n \"title\": \"\ + Exclude\",\n \"type\": \"boolean\"\n }\n },\n \"title\": \"TaskMessageEntityFilter\"\ + ,\n \"type\": \"object\"\n}\n\nEach filter can include:\n- `content`: Filter\ + \ by message content (type, author, data fields)\n- `streaming_status`:\ + \ Filter by status (\"IN_PROGRESS\" or \"DONE\")\n- `exclude`: If true,\ + \ excludes matching messages (default: false)\n\nMultiple filters are combined:\ + \ inclusionary filters (exclude=false) are OR'd together,\nexclusionary\ + \ filters (exclude=true) are OR'd and negated, then both groups are AND'd.\n" + examples: + single_filter: + summary: Filter by content type + value: '{"content": {"type": "text"}}' + multiple_types: + summary: Filter multiple content types (OR) + value: '[{"content": {"type": "text"}}, {"content": {"type": "data"}}]' + with_exclusion: + summary: Include data messages, exclude specific data types + value: '[{"content": {"type": "data"}}, {"content": {"data": {"type": + "error_report"}}, "exclude": true}]' + nested_data: + summary: Filter by nested data field + value: '{"content": {"data": {"type": "report_status_update"}}}' + - name: task_id + in: query + required: true + schema: + type: string + description: The task ID + title: Task Id + description: The task ID + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/TaskMessage' + title: Response List Messages Messages Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /messages/{message_id}: + put: + tags: + - Messages + summary: Update Message + operationId: update_message_messages__message_id__put + parameters: + - name: message_id + in: path + required: true + schema: + type: string + title: Message Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateTaskMessageRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TaskMessage' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Messages + summary: Get Message + operationId: get_message_messages__message_id__get + parameters: + - name: message_id + in: path + required: true + schema: + type: string + title: Message Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TaskMessage' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /messages/paginated: + get: + tags: + - Messages + summary: List Messages Paginated + description: "List messages for a task with cursor-based pagination.\n\nThis\ + \ endpoint is designed for infinite scroll UIs where new messages may arrive\n\ + while paginating through older ones.\n\nArgs:\n task_id: The task ID to\ + \ filter messages by\n limit: Maximum number of messages to return (default:\ + \ 50)\n cursor: Opaque cursor string for pagination. Pass the `next_cursor`\ + \ from\n a previous response to get the next page.\n direction:\ + \ Pagination direction - \"older\" to get older messages (default),\n \ + \ \"newer\" to get newer messages.\n\nReturns:\n PaginatedMessagesResponse\ + \ with:\n - data: List of messages (newest first when direction=\"older\"\ + )\n - next_cursor: Cursor for fetching the next page (null if no more pages)\n\ + \ - has_more: Whether there are more messages to fetch\n\nExample:\n \ + \ First request: GET /messages/paginated?task_id=xxx&limit=50\n Next page:\ + \ GET /messages/paginated?task_id=xxx&limit=50&cursor=" + operationId: list_messages_paginated_messages_paginated_get + parameters: + - name: limit + in: query + required: false + schema: + type: integer + default: 50 + title: Limit + - name: cursor + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Cursor + - name: direction + in: query + required: false + schema: + enum: + - older + - newer + type: string + default: older + title: Direction + - name: filters + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: "JSON-encoded array of TaskMessageEntityFilter objects.\n\n\ + Schema: {\n \"$defs\": {\n \"DataContentEntityOptional\": {\n \ + \ \"properties\": {\n \"type\": {\n \"anyOf\": [\n \ + \ {\n \"const\": \"data\",\n \"type\"\ + : \"string\"\n },\n {\n \"type\": \"\ + null\"\n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The type of the message, in this case `data`.\"\ + ,\n \"title\": \"Type\"\n },\n \"author\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"data\"\ + : {\n \"anyOf\": [\n {\n \"additionalProperties\"\ + : true,\n \"type\": \"object\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The contents\ + \ of the data message.\",\n \"title\": \"Data\"\n }\n\ + \ },\n \"title\": \"DataContentEntityOptional\",\n \"type\"\ + : \"object\"\n },\n \"FileAttachmentEntity\": {\n \"description\"\ + : \"Represents a file attachment in messages.\",\n \"properties\"\ + : {\n \"file_id\": {\n \"description\": \"The unique ID\ + \ of the attached file\",\n \"title\": \"File Id\",\n \ + \ \"type\": \"string\"\n },\n \"name\": {\n \"\ + description\": \"The name of the file\",\n \"title\": \"Name\"\ + ,\n \"type\": \"string\"\n },\n \"size\": {\n \ + \ \"description\": \"The size of the file in bytes\",\n \ + \ \"title\": \"Size\",\n \"type\": \"integer\"\n },\n\ + \ \"type\": {\n \"description\": \"The MIME type or content\ + \ type of the file\",\n \"title\": \"Type\",\n \"type\"\ + : \"string\"\n }\n },\n \"required\": [\n \"file_id\"\ + ,\n \"name\",\n \"size\",\n \"type\"\n ],\n\ + \ \"title\": \"FileAttachmentEntity\",\n \"type\": \"object\"\ + \n },\n \"MessageAuthor\": {\n \"enum\": [\n \"user\"\ + ,\n \"agent\"\n ],\n \"title\": \"MessageAuthor\",\n\ + \ \"type\": \"string\"\n },\n \"MessageStyle\": {\n \"\ + enum\": [\n \"static\",\n \"active\"\n ],\n \"\ + title\": \"MessageStyle\",\n \"type\": \"string\"\n },\n \"\ + ReasoningContentEntityOptional\": {\n \"properties\": {\n \ + \ \"type\": {\n \"anyOf\": [\n {\n \"\ + const\": \"reasoning\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `reasoning`.\",\n \"\ + title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"summary\"\ + : {\n \"anyOf\": [\n {\n \"items\": {\n\ + \ \"type\": \"string\"\n },\n \ + \ \"type\": \"array\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"A list of short reasoning summaries\"\ + ,\n \"title\": \"Summary\"\n },\n \"content\":\ + \ {\n \"anyOf\": [\n {\n \"items\": {\n\ + \ \"type\": \"string\"\n },\n \ + \ \"type\": \"array\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"The reasoning content or chain-of-thought\ + \ text\",\n \"title\": \"Content\"\n }\n },\n \ + \ \"title\": \"ReasoningContentEntityOptional\",\n \"type\": \"\ + object\"\n },\n \"TextContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"text\",\n \"type\": \"string\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The type of the message, in this case `text`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"format\"\ + : {\n \"anyOf\": [\n {\n \"$ref\": \"\ + #/$defs/TextFormat\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"The format of the message. This\ + \ is used by the client to determine how to display the message.\"\n \ + \ },\n \"content\": {\n \"anyOf\": [\n \ + \ {\n \"type\": \"string\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The contents\ + \ of the text message.\",\n \"title\": \"Content\"\n },\n\ + \ \"attachments\": {\n \"anyOf\": [\n {\n \ + \ \"items\": {\n \"$ref\": \"#/$defs/FileAttachmentEntity\"\ + \n },\n \"type\": \"array\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + Optional list of file attachments with structured metadata.\",\n \ + \ \"title\": \"Attachments\"\n }\n },\n \"title\"\ + : \"TextContentEntityOptional\",\n \"type\": \"object\"\n },\n\ + \ \"TextFormat\": {\n \"enum\": [\n \"markdown\",\n \ + \ \"plain\",\n \"code\"\n ],\n \"title\": \"TextFormat\"\ + ,\n \"type\": \"string\"\n },\n \"ToolRequestContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\"\ + : [\n {\n \"const\": \"tool_request\",\n \ + \ \"type\": \"string\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The type of the message,\ + \ in this case `tool_request`.\",\n \"title\": \"Type\"\n \ + \ },\n \"author\": {\n \"anyOf\": [\n {\n\ + \ \"$ref\": \"#/$defs/MessageAuthor\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"tool_call_id\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The ID of the tool call that is being requested.\"\ + ,\n \"title\": \"Tool Call Id\"\n },\n \"name\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The name of the tool that is being requested.\"\ + ,\n \"title\": \"Name\"\n },\n \"arguments\": {\n\ + \ \"anyOf\": [\n {\n \"additionalProperties\"\ + : true,\n \"type\": \"object\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The arguments\ + \ to the tool.\",\n \"title\": \"Arguments\"\n }\n \ + \ },\n \"title\": \"ToolRequestContentEntityOptional\",\n \ + \ \"type\": \"object\"\n },\n \"ToolResponseContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\"\ + : [\n {\n \"const\": \"tool_response\",\n \ + \ \"type\": \"string\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The type of the message,\ + \ in this case `tool_response`.\",\n \"title\": \"Type\"\n \ + \ },\n \"author\": {\n \"anyOf\": [\n \ + \ {\n \"$ref\": \"#/$defs/MessageAuthor\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"tool_call_id\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The ID of the tool call that is being responded\ + \ to.\",\n \"title\": \"Tool Call Id\"\n },\n \"\ + name\": {\n \"anyOf\": [\n {\n \"type\"\ + : \"string\"\n },\n {\n \"type\": \"\ + null\"\n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The name of the tool that is being responded\ + \ to.\",\n \"title\": \"Name\"\n },\n \"content\"\ + : {\n \"anyOf\": [\n {},\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"default\"\ + : null,\n \"description\": \"The result of the tool.\",\n \ + \ \"title\": \"Content\"\n }\n },\n \"title\":\ + \ \"ToolResponseContentEntityOptional\",\n \"type\": \"object\"\n\ + \ }\n },\n \"description\": \"Filter model for TaskMessage - all\ + \ fields optional for flexible filtering.\\n\\nThe `exclude` field determines\ + \ whether this filter is inclusionary or exclusionary.\\nWhen multiple\ + \ filters are provided:\\n- Inclusionary filters (exclude=False) are OR'd\ + \ together\\n- Exclusionary filters (exclude=True) are OR'd together and\ + \ negated with $nor\\n- The two groups are AND'd: (include1 OR include2)\ + \ AND NOT (exclude1 OR exclude2)\",\n \"properties\": {\n \"content\"\ + : {\n \"anyOf\": [\n {\n \"$ref\": \"#/$defs/ToolRequestContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/DataContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/TextContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ToolResponseContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ReasoningContentEntityOptional\"\ + \n },\n {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Filter by message\ + \ content\",\n \"title\": \"Content\"\n },\n \"streaming_status\"\ + : {\n \"anyOf\": [\n {\n \"enum\": [\n \ + \ \"IN_PROGRESS\",\n \"DONE\"\n ],\n \"\ + type\": \"string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \"description\"\ + : \"Filter by streaming status\",\n \"title\": \"Streaming Status\"\ + \n },\n \"exclude\": {\n \"default\": false,\n \"description\"\ + : \"If true, this filter excludes matching messages\",\n \"title\"\ + : \"Exclude\",\n \"type\": \"boolean\"\n }\n },\n \"title\"\ + : \"TaskMessageEntityFilter\",\n \"type\": \"object\"\n}\n\nEach filter\ + \ can include:\n- `content`: Filter by message content (type, author,\ + \ data fields)\n- `streaming_status`: Filter by status (\"IN_PROGRESS\"\ + \ or \"DONE\")\n- `exclude`: If true, excludes matching messages (default:\ + \ false)\n\nMultiple filters are combined: inclusionary filters (exclude=false)\ + \ are OR'd together,\nexclusionary filters (exclude=true) are OR'd and\ + \ negated, then both groups are AND'd.\n" + title: Filters + description: "JSON-encoded array of TaskMessageEntityFilter objects.\n\nSchema:\ + \ {\n \"$defs\": {\n \"DataContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"data\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `data`.\",\n \"title\"\ + : \"Type\"\n },\n \"author\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageAuthor\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"data\": {\n \ + \ \"anyOf\": [\n {\n \"additionalProperties\": true,\n\ + \ \"type\": \"object\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The contents of the data\ + \ message.\",\n \"title\": \"Data\"\n }\n },\n \ + \ \"title\": \"DataContentEntityOptional\",\n \"type\": \"object\"\ + \n },\n \"FileAttachmentEntity\": {\n \"description\": \"Represents\ + \ a file attachment in messages.\",\n \"properties\": {\n \"\ + file_id\": {\n \"description\": \"The unique ID of the attached\ + \ file\",\n \"title\": \"File Id\",\n \"type\": \"string\"\ + \n },\n \"name\": {\n \"description\": \"The name\ + \ of the file\",\n \"title\": \"Name\",\n \"type\": \"\ + string\"\n },\n \"size\": {\n \"description\": \"\ + The size of the file in bytes\",\n \"title\": \"Size\",\n \ + \ \"type\": \"integer\"\n },\n \"type\": {\n \ + \ \"description\": \"The MIME type or content type of the file\",\n \ + \ \"title\": \"Type\",\n \"type\": \"string\"\n }\n\ + \ },\n \"required\": [\n \"file_id\",\n \"name\"\ + ,\n \"size\",\n \"type\"\n ],\n \"title\": \"FileAttachmentEntity\"\ + ,\n \"type\": \"object\"\n },\n \"MessageAuthor\": {\n \"\ + enum\": [\n \"user\",\n \"agent\"\n ],\n \"title\"\ + : \"MessageAuthor\",\n \"type\": \"string\"\n },\n \"MessageStyle\"\ + : {\n \"enum\": [\n \"static\",\n \"active\"\n ],\n\ + \ \"title\": \"MessageStyle\",\n \"type\": \"string\"\n },\n\ + \ \"ReasoningContentEntityOptional\": {\n \"properties\": {\n \ + \ \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"reasoning\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `reasoning`.\",\n \"\ + title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"summary\": {\n \ + \ \"anyOf\": [\n {\n \"items\": {\n \ + \ \"type\": \"string\"\n },\n \"type\":\ + \ \"array\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \"\ + description\": \"A list of short reasoning summaries\",\n \"title\"\ + : \"Summary\"\n },\n \"content\": {\n \"anyOf\":\ + \ [\n {\n \"items\": {\n \"type\"\ + : \"string\"\n },\n \"type\": \"array\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The reasoning content or chain-of-thought text\",\n \"title\"\ + : \"Content\"\n }\n },\n \"title\": \"ReasoningContentEntityOptional\"\ + ,\n \"type\": \"object\"\n },\n \"TextContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\":\ + \ [\n {\n \"const\": \"text\",\n \"\ + type\": \"string\"\n },\n {\n \"type\"\ + : \"null\"\n }\n ],\n \"default\": null,\n\ + \ \"description\": \"The type of the message, in this case `text`.\"\ + ,\n \"title\": \"Type\"\n },\n \"author\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"format\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/TextFormat\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The format of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"content\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The contents of the text message.\",\n \"title\": \"Content\"\ + \n },\n \"attachments\": {\n \"anyOf\": [\n \ + \ {\n \"items\": {\n \"$ref\": \"#/$defs/FileAttachmentEntity\"\ + \n },\n \"type\": \"array\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Optional\ + \ list of file attachments with structured metadata.\",\n \"title\"\ + : \"Attachments\"\n }\n },\n \"title\": \"TextContentEntityOptional\"\ + ,\n \"type\": \"object\"\n },\n \"TextFormat\": {\n \"enum\"\ + : [\n \"markdown\",\n \"plain\",\n \"code\"\n \ + \ ],\n \"title\": \"TextFormat\",\n \"type\": \"string\"\n \ + \ },\n \"ToolRequestContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"tool_request\",\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `tool_request`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"tool_call_id\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The ID of the tool call that is being requested.\",\n \"title\"\ + : \"Tool Call Id\"\n },\n \"name\": {\n \"anyOf\"\ + : [\n {\n \"type\": \"string\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"The\ + \ name of the tool that is being requested.\",\n \"title\": \"\ + Name\"\n },\n \"arguments\": {\n \"anyOf\": [\n \ + \ {\n \"additionalProperties\": true,\n \ + \ \"type\": \"object\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"default\"\ + : null,\n \"description\": \"The arguments to the tool.\",\n \ + \ \"title\": \"Arguments\"\n }\n },\n \"title\"\ + : \"ToolRequestContentEntityOptional\",\n \"type\": \"object\"\n \ + \ },\n \"ToolResponseContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"tool_response\",\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `tool_response`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \"\ + anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"tool_call_id\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The ID of the tool call that is being responded to.\",\n \"\ + title\": \"Tool Call Id\"\n },\n \"name\": {\n \"\ + anyOf\": [\n {\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n }\n\ + \ ],\n \"default\": null,\n \"description\":\ + \ \"The name of the tool that is being responded to.\",\n \"title\"\ + : \"Name\"\n },\n \"content\": {\n \"anyOf\": [\n\ + \ {},\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The result of the tool.\",\n \"title\": \"Content\"\n \ + \ }\n },\n \"title\": \"ToolResponseContentEntityOptional\"\ + ,\n \"type\": \"object\"\n }\n },\n \"description\": \"Filter\ + \ model for TaskMessage - all fields optional for flexible filtering.\\\ + n\\nThe `exclude` field determines whether this filter is inclusionary or\ + \ exclusionary.\\nWhen multiple filters are provided:\\n- Inclusionary filters\ + \ (exclude=False) are OR'd together\\n- Exclusionary filters (exclude=True)\ + \ are OR'd together and negated with $nor\\n- The two groups are AND'd:\ + \ (include1 OR include2) AND NOT (exclude1 OR exclude2)\",\n \"properties\"\ + : {\n \"content\": {\n \"anyOf\": [\n {\n \"$ref\"\ + : \"#/$defs/ToolRequestContentEntityOptional\"\n },\n {\n\ + \ \"$ref\": \"#/$defs/DataContentEntityOptional\"\n },\n\ + \ {\n \"$ref\": \"#/$defs/TextContentEntityOptional\"\n\ + \ },\n {\n \"$ref\": \"#/$defs/ToolResponseContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ReasoningContentEntityOptional\"\ + \n },\n {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Filter by message\ + \ content\",\n \"title\": \"Content\"\n },\n \"streaming_status\"\ + : {\n \"anyOf\": [\n {\n \"enum\": [\n \"\ + IN_PROGRESS\",\n \"DONE\"\n ],\n \"type\":\ + \ \"string\"\n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\": \"Filter\ + \ by streaming status\",\n \"title\": \"Streaming Status\"\n },\n\ + \ \"exclude\": {\n \"default\": false,\n \"description\": \"\ + If true, this filter excludes matching messages\",\n \"title\": \"\ + Exclude\",\n \"type\": \"boolean\"\n }\n },\n \"title\": \"TaskMessageEntityFilter\"\ + ,\n \"type\": \"object\"\n}\n\nEach filter can include:\n- `content`: Filter\ + \ by message content (type, author, data fields)\n- `streaming_status`:\ + \ Filter by status (\"IN_PROGRESS\" or \"DONE\")\n- `exclude`: If true,\ + \ excludes matching messages (default: false)\n\nMultiple filters are combined:\ + \ inclusionary filters (exclude=false) are OR'd together,\nexclusionary\ + \ filters (exclude=true) are OR'd and negated, then both groups are AND'd.\n" + examples: + single_filter: + summary: Filter by content type + value: '{"content": {"type": "text"}}' + multiple_types: + summary: Filter multiple content types (OR) + value: '[{"content": {"type": "text"}}, {"content": {"type": "data"}}]' + with_exclusion: + summary: Include data messages, exclude specific data types + value: '[{"content": {"type": "data"}}, {"content": {"data": {"type": + "error_report"}}, "exclude": true}]' + nested_data: + summary: Filter by nested data field + value: '{"content": {"data": {"type": "report_status_update"}}}' + - name: task_id + in: query + required: true + schema: + type: string + description: The task ID + title: Task Id + description: The task ID + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedMessagesResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /spans: + post: + tags: + - Spans + summary: Create Span + description: Create a new span with the provided parameters + operationId: create_span_spans_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateSpanRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Span' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Spans + summary: List Spans + description: List spans, optionally filtered by trace_id and/or task_id + operationId: list_spans_spans_get + parameters: + - name: trace_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Trace Id + - name: task_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Task Id + - name: limit + in: query + required: false + schema: + type: integer + maximum: 1000 + minimum: 1 + default: 50 + title: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + default: 1 + title: Page Number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Order By + - name: order_direction + in: query + required: false + schema: + type: string + default: desc + title: Order Direction + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Span' + title: Response List Spans Spans Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /spans/{span_id}: + patch: + tags: + - Spans + summary: Partial Update Span + description: Update a span with the provided output data and mark it as complete + operationId: partial_update_span_spans__span_id__patch + parameters: + - name: span_id + in: path + required: true + schema: + type: string + title: Span Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateSpanRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Span' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Spans + summary: Get Span + description: Get a span by ID + operationId: get_span_spans__span_id__get + parameters: + - name: span_id + in: path + required: true + schema: + type: string + title: Span Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Span' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /states: + post: + tags: + - States + summary: Create Task State + operationId: create_task_state_states_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateStateRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/State' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - States + summary: List States + description: List all states, optionally filtered by query parameters. + operationId: filter_states_states_get + parameters: + - name: task_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Task ID + title: Task Id + description: Task ID + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Agent ID + title: Agent Id + description: Agent ID + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + description: Limit + default: 50 + title: Limit + description: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + description: Page number + default: 1 + title: Page Number + description: Page number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Field to order by + title: Order By + description: Field to order by + - name: order_direction + in: query + required: false + schema: + type: string + description: Order direction (asc or desc) + default: desc + title: Order Direction + description: Order direction (asc or desc) + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/State' + title: Response Filter States States Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /states/{state_id}: + get: + tags: + - States + summary: Get State by State ID + description: Get a state by its unique state ID. + operationId: get_state_states__state_id__get + parameters: + - name: state_id + in: path + required: true + schema: + type: string + title: State Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/State' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + tags: + - States + summary: Update Task State + operationId: update_task_state_states__state_id__put + parameters: + - name: state_id + in: path + required: true + schema: + type: string + title: State Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateStateRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/State' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - States + summary: Delete Task State + operationId: delete_task_state_states__state_id__delete + parameters: + - name: state_id + in: path + required: true + schema: + type: string + title: State Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/State' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /events/{event_id}: + get: + tags: + - Events + summary: Get Event + operationId: get_event_events__event_id__get + parameters: + - name: event_id + in: path + required: true + schema: + type: string + title: Event Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Event' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /events: + get: + tags: + - Events + summary: List Events + description: 'List events for a specific task and agent. + + + Optionally filter for events after a specific sequence ID. + + Results are ordered by sequence_id.' + operationId: list_events_events_get + parameters: + - name: last_processed_event_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Optional event ID to get events after this ID + title: Last Processed Event Id + description: Optional event ID to get events after this ID + - name: limit + in: query + required: false + schema: + anyOf: + - type: integer + maximum: 1000 + minimum: 1 + - type: 'null' + description: Optional limit on number of results + title: Limit + description: Optional limit on number of results + - name: task_id + in: query + required: true + schema: + type: string + description: The task ID to filter events by + title: Task Id + description: The task ID to filter events by + - name: agent_id + in: query + required: true + schema: + type: string + description: The agent ID to filter events by + title: Agent Id + description: The agent ID to filter events by + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Event' + title: Response List Events Events Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tracker/{tracker_id}: + get: + tags: + - Agent Task Tracker + summary: Get Agent Task Tracker + description: Get agent task tracker by tracker ID + operationId: get_agent_task_tracker_tracker__tracker_id__get + parameters: + - name: tracker_id + in: path + required: true + schema: + type: string + title: Tracker Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentTaskTracker' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + tags: + - Agent Task Tracker + summary: Update Agent Task Tracker + description: Update agent task tracker by tracker ID + operationId: update_agent_task_tracker_tracker__tracker_id__put + parameters: + - name: tracker_id + in: path + required: true + schema: + type: string + title: Tracker Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAgentTaskTrackerRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentTaskTracker' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tracker: + get: + tags: + - Agent Task Tracker + summary: List Agent Task Trackers + description: List all agent task trackers, optionally filtered by query parameters. + operationId: filter_agent_task_tracker_tracker_get + parameters: + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Agent ID + title: Agent Id + description: Agent ID + - name: task_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Task ID + title: Task Id + description: Task ID + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + description: Limit + default: 50 + title: Limit + description: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + description: Page number + default: 1 + title: Page Number + description: Page number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Field to order by + title: Order By + description: Field to order by + - name: order_direction + in: query + required: false + schema: + type: string + description: Order direction (asc or desc) + default: desc + title: Order Direction + description: Order direction (asc or desc) + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AgentTaskTracker' + title: Response Filter Agent Task Tracker Tracker Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agent_api_keys: + post: + tags: + - Agent APIKeys + summary: Create Api Key + operationId: create_api_key_agent_api_keys_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAPIKeyRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAPIKeyResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Agent APIKeys + summary: List API keys for an agent ID + description: List API keys for an agent ID. + operationId: list_agent_api_keys_agent_api_keys_get + parameters: + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: agent_name + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Name + - name: limit + in: query + required: false + schema: + type: integer + maximum: 1000 + minimum: 1 + default: 50 + title: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + default: 1 + title: Page Number + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AgentAPIKey' + title: Response List Agent Api Keys Agent Api Keys Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agent_api_keys/name/{name}: + get: + tags: + - Agent APIKeys + summary: Return named API key for the agent ID + description: Return named API key for the agent ID. + operationId: get_agent_api_key_by_name_agent_api_keys_name__name__get + parameters: + - name: name + in: path + required: true + schema: + type: string + title: Name + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: agent_name + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Name + - name: api_key_type + in: query + required: false + schema: + $ref: '#/components/schemas/AgentAPIKeyType' + default: external + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentAPIKey' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agent_api_keys/{id}: + get: + tags: + - Agent APIKeys + summary: Return the API key by ID + description: Return API key by ID. + operationId: get_agent_api_key_agent_api_keys__id__get + parameters: + - name: id + in: path + required: true + schema: + type: string + title: Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentAPIKey' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Agent APIKeys + summary: Delete API key by ID + description: Delete API key by ID. + operationId: delete_agent_api_key_agent_api_keys__id__delete + parameters: + - name: id + in: path + required: true + schema: + type: string + title: Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: string + title: Response Delete Agent Api Key Agent Api Keys Id Delete + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agent_api_keys/name/{api_key_name}: + delete: + tags: + - Agent APIKeys + summary: Delete API key by name + description: Delete API key by name. + operationId: delete_agent_api_key_by_name_agent_api_keys_name__api_key_name__delete + parameters: + - name: api_key_name + in: path + required: true + schema: + type: string + title: Api Key Name + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: agent_name + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Name + - name: api_key_type + in: query + required: false + schema: + $ref: '#/components/schemas/AgentAPIKeyType' + default: external + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: string + title: Response Delete Agent Api Key By Name Agent Api Keys Name Api + Key Name Delete + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /deployment-history/{deployment_id}: + get: + tags: + - Deployment History + summary: Get Deployment by ID + description: Get a deployment record by its unique ID. + operationId: get_deployment_by_id_deployment_history__deployment_id__get + parameters: + - name: deployment_id + in: path + required: true + schema: + type: string + title: Deployment Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeploymentHistory' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /deployment-history: + get: + tags: + - Deployment History + summary: List Deployments for an agent + description: List deployment history for an agent. + operationId: list_deployments_deployment_history_get + parameters: + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: agent_name + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Name + - name: limit + in: query + required: false + schema: + type: integer + default: 50 + title: Limit + - name: page_number + in: query + required: false + schema: + type: integer + default: 1 + title: Page Number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Order By + - name: order_direction + in: query + required: false + schema: + type: string + default: desc + title: Order Direction + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/DeploymentHistory' + title: Response List Deployments Deployment History Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/deployments: + post: + tags: + - Deployments + summary: Create Deployment + description: Create a new deployment record in PENDING status. + operationId: create_deployment_agents__agent_id__deployments_post + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateDeploymentRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Deployments + summary: List Deployments + description: List deployments for an agent, newest first. + operationId: list_deployments_agents__agent_id__deployments_get + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + description: Limit + default: 50 + title: Limit + description: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + description: Page number + default: 1 + title: Page Number + description: Page number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Field to order by + title: Order By + description: Field to order by + - name: order_direction + in: query + required: false + schema: + type: string + description: Order direction (asc or desc) + default: desc + title: Order Direction + description: Order direction (asc or desc) + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Deployment' + title: Response List Deployments Agents Agent Id Deployments Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/deployments/{deployment_id}: + get: + tags: + - Deployments + summary: Get Deployment + description: Get a specific deployment by ID. + operationId: get_deployment_agents__agent_id__deployments__deployment_id__get + parameters: + - name: deployment_id + in: path + required: true + schema: + type: string + title: Deployment Id + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Deployments + summary: Delete Deployment + description: Delete a non-production deployment. + operationId: delete_deployment_agents__agent_id__deployments__deployment_id__delete + parameters: + - name: deployment_id + in: path + required: true + schema: + type: string + title: Deployment Id + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/deployments/{deployment_id}/promote: + post: + tags: + - Deployments + summary: Promote Deployment + description: Promote a deployment to production with atomic cutover. + operationId: promote_deployment_agents__agent_id__deployments__deployment_id__promote_post + parameters: + - name: deployment_id + in: path + required: true + schema: + type: string + title: Deployment Id + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/deployments/{deployment_id}/rpc: + post: + tags: + - Deployments + summary: Preview RPC + description: Send an RPC request to a specific deployment (for preview testing). + operationId: handle_deployment_rpc_agents__agent_id__deployments__deployment_id__rpc_post + parameters: + - name: deployment_id + in: path + required: true + schema: + type: string + title: Deployment Id + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/schedules: + post: + tags: + - Schedules + summary: Create Schedule + description: Create a new schedule for recurring workflow execution for an agent. + operationId: create_schedule_agents__agent_id__schedules_post + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateScheduleRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Schedules + summary: List Agent Schedules + description: List all schedules for an agent. + operationId: list_schedules_agents__agent_id__schedules_get + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: page_size + in: query + required: false + schema: + type: integer + maximum: 1000 + minimum: 1 + default: 100 + title: Page Size + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleListResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/schedules/{schedule_name}: + get: + tags: + - Schedules + summary: Get Schedule + description: Get details of a schedule by its name. + operationId: get_schedule_agents__agent_id__schedules__schedule_name__get + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: schedule_name + in: path + required: true + schema: + type: string + title: Schedule Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Schedules + summary: Delete Schedule + description: Delete a schedule permanently. + operationId: delete_schedule_agents__agent_id__schedules__schedule_name__delete + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: schedule_name + in: path + required: true + schema: + type: string + title: Schedule Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/schedules/{schedule_name}/pause: + post: + tags: + - Schedules + summary: Pause Schedule + description: Pause a schedule to stop it from executing. + operationId: pause_schedule_agents__agent_id__schedules__schedule_name__pause_post + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: schedule_name + in: path + required: true + schema: + type: string + title: Schedule Name + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/PauseScheduleRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/schedules/{schedule_name}/unpause: + post: + tags: + - Schedules + summary: Unpause Schedule + description: Unpause/resume a schedule to allow it to execute again. + operationId: unpause_schedule_agents__agent_id__schedules__schedule_name__unpause_post + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: schedule_name + in: path + required: true + schema: + type: string + title: Schedule Name + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/UnpauseScheduleRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/schedules/{schedule_name}/trigger: + post: + tags: + - Schedules + summary: Trigger Schedule + description: Trigger a schedule to run immediately, regardless of its regular + schedule. + operationId: trigger_schedule_agents__agent_id__schedules__schedule_name__trigger_post + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: schedule_name + in: path + required: true + schema: + type: string + title: Schedule Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /checkpoints/get-tuple: + post: + tags: + - Checkpoints + summary: Get Checkpoint Tuple + operationId: get_checkpoint_tuple_checkpoints_get_tuple_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetCheckpointTupleRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/CheckpointTupleResponse' + - type: 'null' + title: Response Get Checkpoint Tuple Checkpoints Get Tuple Post + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /checkpoints/put: + post: + tags: + - Checkpoints + summary: Put Checkpoint + operationId: put_checkpoint_checkpoints_put_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PutCheckpointRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/PutCheckpointResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /checkpoints/put-writes: + post: + tags: + - Checkpoints + summary: Put Writes + operationId: put_writes_checkpoints_put_writes_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PutWritesRequest' + required: true + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /checkpoints/list: + post: + tags: + - Checkpoints + summary: List Checkpoints + operationId: list_checkpoints_checkpoints_list_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ListCheckpointsRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + items: + $ref: '#/components/schemas/CheckpointListItem' + type: array + title: Response List Checkpoints Checkpoints List Post + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /checkpoints/delete-thread: + post: + tags: + - Checkpoints + summary: Delete Thread + operationId: delete_thread_checkpoints_delete_thread_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteThreadRequest' + required: true + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/export: + get: + tags: + - task-retention + summary: Export Task + description: 'Build a self-contained snapshot of a task''s content surfaces. + + + Returns the exact payload format that POST /rehydrate accepts, so + + export → clean → rehydrate is a round-trip-equivalent operation.' + operationId: export_task_tasks__task_id__export_get + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ExportTaskResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + post: + tags: + - task-retention + summary: Export Task To Url + description: 'Build the task snapshot and PUT it to a caller-supplied presigned + URL. + + + Use this when the snapshot is too large for a JSON response body (long + + conversations, deep reasoning content, many attachments). The upload URL + + must be https and resolve to a public address — see SSRF guard.' + operationId: export_task_to_url_tasks__task_id__export_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ExportTaskToUrlRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ExportTaskToUrlResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/clean: + post: + tags: + - task-retention + summary: Clean Task + description: 'Delete content-bearing rows for a stale task. + + + Refuses on active tasks, in-flight workflows, or unprocessed events + + regardless of `force`. The `force=true` flag only bypasses the + + idle-threshold check.' + operationId: clean_task_tasks__task_id__clean_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CleanTaskRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/CleanTaskResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/rehydrate: + post: + tags: + - task-retention + summary: Rehydrate Task + description: 'Restore content-bearing rows from a snapshot. + + + Two modes: + + - Inline: caller provides messages and task_states in the request body. + + - URL: caller provides snapshot_url; Agentex downloads and parses it. + + + Refuses if the task isn''t currently in a cleaned state, or if any supplied + + message/state ID already exists in Mongo (catches double-rehydrate).' + operationId: rehydrate_task_tasks__task_id__rehydrate_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/RehydrateTaskRequest' + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' +components: + schemas: + ACPType: + type: string + enum: + - sync + - async + - agentic + title: ACPType + Agent: + properties: + id: + type: string + title: Id + description: The unique identifier of the agent. + name: + type: string + title: Name + description: The unique name of the agent. + description: + type: string + title: Description + description: The description of the action. + status: + $ref: '#/components/schemas/AgentStatus' + description: The status of the action, indicating if it's building, ready, + failed, etc. + default: Unknown + acp_type: + $ref: '#/components/schemas/ACPType' + description: The type of the ACP Server (Either sync or async) + status_reason: + anyOf: + - type: string + - type: 'null' + title: Status Reason + description: The reason for the status of the action. + created_at: + type: string + format: date-time + title: Created At + description: The timestamp when the agent was created + updated_at: + type: string + format: date-time + title: Updated At + description: The timestamp when the agent was last updated + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: The metadata for the agent's registration. + registered_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Registered At + description: The timestamp when the agent was last registered + agent_input_type: + anyOf: + - $ref: '#/components/schemas/AgentInputType' + - type: 'null' + description: The type of input the agent expects. + production_deployment_id: + anyOf: + - type: string + - type: 'null' + title: Production Deployment Id + description: ID of the current production deployment. + type: object + required: + - id + - name + - description + - acp_type + - created_at + - updated_at + title: Agent + AgentAPIKey: + properties: + id: + type: string + title: Id + description: The unique identifier of the agent API key. + agent_id: + type: string + title: Agent Id + description: The UUID of the agent + created_at: + type: string + format: date-time + title: Created At + description: When the agent API key was created + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: The optional name of the agent API key. + api_key_type: + $ref: '#/components/schemas/AgentAPIKeyType' + description: The type of the agent API key (either internal or external) + type: object + required: + - id + - agent_id + - created_at + - name + - api_key_type + title: AgentAPIKey + AgentAPIKeyType: + type: string + enum: + - internal + - external + - github + - slack + title: AgentAPIKeyType + AgentInputType: + type: string + enum: + - text + - json + title: AgentInputType + AgentRPCMethod: + type: string + enum: + - event/send + - task/create + - message/send + - task/cancel + title: AgentRPCMethod + AgentRPCParams: + anyOf: + - $ref: '#/components/schemas/CreateTaskRequest' + - $ref: '#/components/schemas/CancelTaskRequest' + - $ref: '#/components/schemas/SendMessageRequest' + - $ref: '#/components/schemas/SendEventRequest' + title: AgentRPCParams + description: The parameters for the agent RPC request + AgentRPCRequest: + properties: + jsonrpc: + type: string + const: '2.0' + title: Jsonrpc + default: '2.0' + method: + $ref: '#/components/schemas/AgentRPCMethod' + params: + $ref: '#/components/schemas/AgentRPCParams' + id: + anyOf: + - type: integer + - type: string + - type: 'null' + title: Id + type: object + required: + - method + - params + title: AgentRPCRequest + AgentRPCResponse: + properties: + jsonrpc: + type: string + const: '2.0' + title: Jsonrpc + default: '2.0' + result: + $ref: '#/components/schemas/AgentRPCResult' + description: The result of the agent RPC request + error: + anyOf: + - {} + - type: 'null' + title: Error + id: + anyOf: + - type: integer + - type: string + - type: 'null' + title: Id + type: object + required: + - result + title: AgentRPCResponse + AgentRPCResult: + anyOf: + - items: + $ref: '#/components/schemas/TaskMessage' + type: array + - $ref: '#/components/schemas/TaskMessageUpdate' + - $ref: '#/components/schemas/Task' + - $ref: '#/components/schemas/Event' + - type: 'null' + title: AgentRPCResult + AgentStatus: + type: string + enum: + - Ready + - Failed + - Unknown + - Deleted + - Unhealthy + - BuildOnly + title: AgentStatus + AgentTaskTracker: + properties: + id: + type: string + title: Id + description: The UUID of the agent task tracker + agent_id: + type: string + title: Agent Id + description: The UUID of the agent + task_id: + type: string + title: Task Id + description: The UUID of the task + status: + anyOf: + - type: string + - type: 'null' + title: Status + description: Processing status + status_reason: + anyOf: + - type: string + - type: 'null' + title: Status Reason + description: Optional status reason + last_processed_event_id: + anyOf: + - type: string + - type: 'null' + title: Last Processed Event Id + description: The last processed event ID + created_at: + type: string + format: date-time + title: Created At + description: When the agent task tracker was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: When the agent task tracker was last updated + type: object + required: + - id + - agent_id + - task_id + - created_at + title: AgentTaskTracker + BatchCreateTaskMessagesRequest: + properties: + task_id: + type: string + title: The unique id of the task to send the messages to + contents: + items: + $ref: '#/components/schemas/TaskMessageContent' + type: array + title: The messages to send to the task. The order of the messages will + be the order they are added to the task. + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Optional caller-supplied base creation timestamp for the batch + description: Optional base timestamp. Each message in the batch is stamped + with base + i milliseconds to guarantee unique, monotonic ordering. If + omitted, the server stamps datetime.now(UTC) at insert time. + type: object + required: + - task_id + - contents + title: BatchCreateTaskMessagesRequest + BatchUpdateTaskMessagesRequest: + properties: + task_id: + type: string + title: The unique id of the task to update the messages of + updates: + additionalProperties: + $ref: '#/components/schemas/TaskMessageContent' + type: object + title: The updates to apply to the messages. The key is the TaskMessage + id and the value is the TaskMessageContent to update the message with. + type: object + required: + - task_id + - updates + title: BatchUpdateTaskMessagesRequest + BlobData: + properties: + channel: + type: string + title: Channel name + version: + type: string + title: Channel version + type: + type: string + title: Serialization type tag + blob: + anyOf: + - type: string + - type: 'null' + title: Base64-encoded binary data + type: object + required: + - channel + - version + - type + title: BlobData + BlobResponse: + properties: + channel: + type: string + title: Channel + version: + type: string + title: Version + type: + type: string + title: Type + blob: + anyOf: + - type: string + - type: 'null' + title: Blob + type: object + required: + - channel + - version + - type + title: BlobResponse + CancelTaskRequest: + properties: + task_id: + anyOf: + - type: string + - type: 'null' + title: Task Id + description: The ID of the task to cancel. Either this or task_name must + be provided. + task_name: + anyOf: + - type: string + - type: 'null' + title: Task Name + description: The name of the task to cancel. Either this or task_id must + be provided. + type: object + title: CancelTaskRequest + CheckpointListItem: + properties: + thread_id: + type: string + title: Thread Id + checkpoint_ns: + type: string + title: Checkpoint Ns + checkpoint_id: + type: string + title: Checkpoint Id + parent_checkpoint_id: + anyOf: + - type: string + - type: 'null' + title: Parent Checkpoint Id + checkpoint: + additionalProperties: true + type: object + title: Checkpoint + metadata: + additionalProperties: true + type: object + title: Metadata + type: object + required: + - thread_id + - checkpoint_ns + - checkpoint_id + - checkpoint + - metadata + title: CheckpointListItem + CheckpointTupleResponse: + properties: + thread_id: + type: string + title: Thread Id + checkpoint_ns: + type: string + title: Checkpoint Ns + checkpoint_id: + type: string + title: Checkpoint Id + parent_checkpoint_id: + anyOf: + - type: string + - type: 'null' + title: Parent Checkpoint Id + checkpoint: + additionalProperties: true + type: object + title: Checkpoint + metadata: + additionalProperties: true + type: object + title: Metadata + blobs: + items: + $ref: '#/components/schemas/BlobResponse' + type: array + title: Blobs + pending_writes: + items: + $ref: '#/components/schemas/WriteResponse' + type: array + title: Pending Writes + type: object + required: + - thread_id + - checkpoint_ns + - checkpoint_id + - checkpoint + - metadata + title: CheckpointTupleResponse + CleanTaskRequest: + properties: + force: + type: boolean + title: Force + description: Skip the idle-threshold check. Active-workflow and unprocessed-events + checks still apply. Admin use only. + default: false + idle_days: + type: integer + minimum: 1.0 + title: Idle Days + description: Idle threshold in days (ignored when force=true). + default: 7 + type: object + title: CleanTaskRequest + CleanTaskResponse: + properties: + task_id: + type: string + title: Task Id + cleaned_at: + type: string + format: date-time + title: Cleaned At + messages_deleted: + type: integer + title: Messages Deleted + task_states_deleted: + type: integer + title: Task States Deleted + events_deleted: + type: integer + title: Events Deleted + type: object + required: + - task_id + - cleaned_at + - messages_deleted + - task_states_deleted + - events_deleted + title: CleanTaskResponse + CreateAPIKeyRequest: + properties: + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + description: The UUID of the agent + agent_name: + anyOf: + - type: string + - type: 'null' + title: Agent Name + description: The name of the agent - if not provided, the agent_id must + be set. + name: + type: string + title: Name + description: The name of the agent's API key. + api_key_type: + $ref: '#/components/schemas/AgentAPIKeyType' + description: The type of the agent API key (external by default). + default: external + api_key: + anyOf: + - type: string + - type: 'null' + title: Api Key + description: Optionally provide the API key value - if not set, one will + be generated. + type: object + required: + - name + title: CreateAPIKeyRequest + CreateAPIKeyResponse: + properties: + id: + type: string + title: Id + description: The unique identifier of the agent API key. + agent_id: + type: string + title: Agent Id + description: The UUID of the agent + created_at: + type: string + format: date-time + title: Created At + description: When the agent API key was created + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: The optional name of the agent API key. + api_key_type: + $ref: '#/components/schemas/AgentAPIKeyType' + description: The type of the created agent API key (external). + api_key: + type: string + title: Api Key + description: The value of the newly created API key. + type: object + required: + - id + - agent_id + - created_at + - name + - api_key_type + - api_key + title: CreateAPIKeyResponse + CreateDeploymentRequest: + properties: + docker_image: + type: string + title: Docker Image + description: Full Docker image URI. + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: Git/build metadata (commit_hash, branch_name, author_name, + author_email, build_timestamp). + sgp_deploy_id: + anyOf: + - type: string + - type: 'null' + title: Sgp Deploy Id + description: SGP deployment ID. + helm_release_name: + anyOf: + - type: string + - type: 'null' + title: Helm Release Name + description: Helm release name. + type: object + required: + - docker_image + title: CreateDeploymentRequest + CreateScheduleRequest: + properties: + name: + type: string + maxLength: 64 + minLength: 1 + pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$ + title: Schedule Name + description: Human-readable name for the schedule (e.g., 'weekly-profiling'). + Will be combined with agent_id to form the full schedule_id. + workflow_name: + type: string + title: Workflow Name + description: Name of the Temporal workflow to execute (e.g., 'sae-orchestrator') + task_queue: + type: string + title: Task Queue + description: Temporal task queue where the agent's worker is listening + workflow_params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Workflow Parameters + description: Parameters to pass to the workflow + cron_expression: + anyOf: + - type: string + - type: 'null' + title: Cron Expression + description: Cron expression for scheduling (e.g., '0 0 * * 0' for weekly + on Sunday) + interval_seconds: + anyOf: + - type: integer + minimum: 1.0 + - type: 'null' + title: Interval Seconds + description: Alternative to cron - run every N seconds + execution_timeout_seconds: + anyOf: + - type: integer + minimum: 1.0 + - type: 'null' + title: Execution Timeout + description: Maximum time in seconds for each workflow execution + start_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Start At + description: When the schedule should start being active + end_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: End At + description: When the schedule should stop being active + paused: + type: boolean + title: Paused + description: Whether to create the schedule in a paused state + default: false + type: object + required: + - name + - workflow_name + - task_queue + title: CreateScheduleRequest + description: Request model for creating a new schedule for an agent + CreateSpanRequest: + properties: + id: + anyOf: + - type: string + - type: 'null' + title: Unique Span ID + description: Unique identifier for the span. If not provided, an ID will + be generated. + trace_id: + type: string + title: The trace ID for this span + description: Unique identifier for the trace this span belongs to + task_id: + anyOf: + - type: string + - type: 'null' + title: The task ID this span is associated with + description: ID of the task this span belongs to + parent_id: + anyOf: + - type: string + - type: 'null' + title: The parent span ID if this is a child span + description: ID of the parent span if this is a child span in a trace + name: + type: string + title: The name of the span + description: Name that describes what operation this span represents + start_time: + type: string + format: date-time + title: The start time of the span + description: The time the span started + end_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The end time of the span + description: The time the span ended + input: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The input data for the span + description: Input parameters or data for the operation + output: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The output data from the span + description: Output data resulting from the operation + data: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: Additional data associated with the span + description: Any additional metadata or context for the span + type: object + required: + - trace_id + - name + - start_time + title: CreateSpanRequest + CreateStateRequest: + properties: + task_id: + type: string + title: The unique id of the task to send the state to + agent_id: + type: string + title: The unique id of the agent to send the state to + state: + additionalProperties: true + type: object + title: The state to send to the task. + type: object + required: + - task_id + - agent_id + - state + title: CreateStateRequest + CreateTaskMessageRequest: + properties: + task_id: + type: string + title: The unique id of the task to send the message to + content: + $ref: '#/components/schemas/TaskMessageContent' + title: The message to send to the task. + streaming_status: + anyOf: + - type: string + enum: + - IN_PROGRESS + - DONE + - type: 'null' + title: The streaming status of the message + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Optional caller-supplied creation timestamp + description: Optional timestamp for the message. Workflow callers should + pass workflow.now() (Temporal's deterministic monotonic clock) so that + two awaited messages.create calls from the same workflow are guaranteed + to have monotonic timestamps regardless of HTTP scheduling at the server. + If omitted, the server's wall clock at insert time is used. + type: object + required: + - task_id + - content + title: CreateTaskMessageRequest + CreateTaskRequest: + properties: + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: 'Optional human-readable name for the task. When set it must + be globally unique. task/create is get-or-create by name: reusing an existing + name returns the existing task (with its prior history) instead of creating + a new one, so omit name (or make it unique, e.g. by appending a UUID) + whenever each call should produce a fresh task.' + params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Params + description: The parameters for the task. On a get-or-create by name, providing + params overwrites the existing task's params (it is not a pure read). + task_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task Metadata + description: Caller-provided metadata to persist on the task row. Only applied + at task creation; ignored if a task with this name already exists. Forwarded + to the agent inside the ACP payload for backward compatibility. + type: object + title: CreateTaskRequest + DataContent: + properties: + type: + type: string + const: data + title: Type + description: The type of the message, in this case `data`. + default: data + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + data: + additionalProperties: true + type: object + title: Data + description: The contents of the data message. + type: object + required: + - author + - data + title: DataContent + DataContentEntity: + properties: + type: + type: string + const: data + title: Type + description: The type of the message, in this case `data`. + default: data + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + data: + additionalProperties: true + type: object + title: Data + description: The contents of the data message. + type: object + required: + - author + - data + title: DataContentEntity + DataDelta: + properties: + type: + type: string + const: data + title: Type + default: data + data_delta: + anyOf: + - type: string + - type: 'null' + title: Data Delta + default: '' + type: object + title: DataDelta + description: Delta for data updates + DeleteResponse: + properties: + id: + type: string + title: Id + message: + type: string + title: Message + type: object + required: + - id + - message + title: DeleteResponse + DeleteThreadRequest: + properties: + thread_id: + type: string + title: Thread ID + type: object + required: + - thread_id + title: DeleteThreadRequest + Deployment: + properties: + id: + type: string + title: Id + description: The unique identifier of the deployment. + agent_id: + type: string + title: Agent Id + description: The agent this deployment belongs to. + docker_image: + type: string + title: Docker Image + description: Full Docker image URI. + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: Git/build metadata from the agent pod. + status: + $ref: '#/components/schemas/DeploymentStatus' + description: Current deployment status. + acp_url: + anyOf: + - type: string + - type: 'null' + title: Acp Url + description: ACP URL set when agent registers. + is_production: + type: boolean + title: Is Production + description: Whether this is the production deployment. + sgp_deploy_id: + anyOf: + - type: string + - type: 'null' + title: Sgp Deploy Id + description: Correlates to SGP's agentex_deploys.id. + helm_release_name: + anyOf: + - type: string + - type: 'null' + title: Helm Release Name + description: Helm release name for cleanup. + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: When the deployment was created. + promoted_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Promoted At + description: When promoted to production. + expires_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Expires At + description: When marked for cleanup. + type: object + required: + - id + - agent_id + - docker_image + - status + - is_production + title: Deployment + DeploymentHistory: + properties: + id: + type: string + title: Id + description: The unique identifier of the deployment record + agent_id: + type: string + title: Agent Id + description: The ID of the agent this deployment belongs to + author_name: + type: string + title: Author Name + description: Name of the commit author + author_email: + type: string + title: Author Email + description: Email of the commit author + branch_name: + type: string + title: Branch Name + description: Name of the branch + build_timestamp: + type: string + format: date-time + title: Build Timestamp + description: When the build was created + deployment_timestamp: + type: string + format: date-time + title: Deployment Timestamp + description: When this deployment was first seen in the system + commit_hash: + type: string + title: Commit Hash + description: Git commit hash for this deployment + type: object + required: + - id + - agent_id + - author_name + - author_email + - branch_name + - build_timestamp + - deployment_timestamp + - commit_hash + title: DeploymentHistory + description: API schema for deployment history. + DeploymentStatus: + type: string + enum: + - Pending + - Ready + - Failed + title: DeploymentStatus + Event: + properties: + id: + type: string + title: Id + description: The UUID of the event + sequence_id: + type: integer + title: Sequence Id + description: The sequence ID of the event + task_id: + type: string + title: Task Id + description: The UUID of the task that the event belongs to + agent_id: + type: string + title: Agent Id + description: The UUID of the agent that the event belongs to + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: The timestamp of the event + content: + anyOf: + - $ref: '#/components/schemas/TaskMessageContent' + - type: 'null' + description: The content of the event + type: object + required: + - id + - sequence_id + - task_id + - agent_id + title: Event + ExportTaskResponse: + properties: + task_id: + type: string + title: Task Id + messages: + items: + $ref: '#/components/schemas/TaskMessageEntity' + type: array + title: Messages + task_states: + items: + $ref: '#/components/schemas/StateEntity' + type: array + title: Task States + type: object + required: + - task_id + title: ExportTaskResponse + description: Wire format mirrors the entity directly — schema parity is intentional. + ExportTaskToUrlRequest: + properties: + upload_url: + type: string + maxLength: 2083 + minLength: 1 + format: uri + title: Upload Url + description: Presigned PUT URL where Agentex will upload the task snapshot + as JSON. Must be https; must resolve to a public address. + type: object + required: + - upload_url + title: ExportTaskToUrlRequest + ExportTaskToUrlResponse: + properties: + task_id: + type: string + title: Task Id + upload_url: + type: string + title: Upload Url + uploaded_bytes: + type: integer + title: Uploaded Bytes + messages_count: + type: integer + title: Messages Count + task_states_count: + type: integer + title: Task States Count + type: object + required: + - task_id + - upload_url + - uploaded_bytes + - messages_count + - task_states_count + title: ExportTaskToUrlResponse + FileAttachment: + properties: + file_id: + type: string + title: File Id + description: The unique ID of the attached file + name: + type: string + title: Name + description: The name of the file + size: + type: integer + title: Size + description: The size of the file in bytes + type: + type: string + title: Type + description: The MIME type or content type of the file + type: object + required: + - file_id + - name + - size + - type + title: FileAttachment + description: Represents a file attachment in messages. + FileAttachmentEntity: + properties: + file_id: + type: string + title: File Id + description: The unique ID of the attached file + name: + type: string + title: Name + description: The name of the file + size: + type: integer + title: Size + description: The size of the file in bytes + type: + type: string + title: Type + description: The MIME type or content type of the file + type: object + required: + - file_id + - name + - size + - type + title: FileAttachmentEntity + description: Represents a file attachment in messages. + GetCheckpointTupleRequest: + properties: + thread_id: + type: string + title: Thread ID + checkpoint_ns: + type: string + title: Checkpoint namespace + default: '' + checkpoint_id: + anyOf: + - type: string + - type: 'null' + title: Checkpoint ID (None = latest) + type: object + required: + - thread_id + title: GetCheckpointTupleRequest + HTTPValidationError: + properties: + detail: + items: + $ref: '#/components/schemas/ValidationError' + type: array + title: Detail + type: object + title: HTTPValidationError + ListCheckpointsRequest: + properties: + thread_id: + type: string + title: Thread ID + checkpoint_ns: + anyOf: + - type: string + - type: 'null' + title: Checkpoint namespace + before_checkpoint_id: + anyOf: + - type: string + - type: 'null' + title: Before checkpoint ID + filter_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Metadata filter (JSONB @>) + limit: + type: integer + maximum: 1000.0 + minimum: 1.0 + title: Max results + default: 100 + type: object + required: + - thread_id + title: ListCheckpointsRequest + MessageAuthor: + type: string + enum: + - user + - agent + title: MessageAuthor + MessageStyle: + type: string + enum: + - static + - active + title: MessageStyle + PaginatedMessagesResponse: + properties: + data: + items: + $ref: '#/components/schemas/TaskMessage' + type: array + title: Data + description: List of messages + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor + description: Cursor for fetching the next page of older messages + has_more: + type: boolean + title: Has More + description: Whether there are more messages to fetch + default: false + type: object + required: + - data + title: PaginatedMessagesResponse + description: Response with cursor pagination metadata. + PauseScheduleRequest: + properties: + note: + anyOf: + - type: string + - type: 'null' + title: Note + description: Optional note explaining why the schedule was paused + type: object + title: PauseScheduleRequest + description: Request model for pausing a schedule + PutCheckpointRequest: + properties: + thread_id: + type: string + title: Thread ID + checkpoint_ns: + type: string + title: Checkpoint namespace + default: '' + checkpoint_id: + type: string + title: Checkpoint ID + parent_checkpoint_id: + anyOf: + - type: string + - type: 'null' + title: Parent checkpoint ID + checkpoint: + additionalProperties: true + type: object + title: Checkpoint JSONB payload + metadata: + additionalProperties: true + type: object + title: Checkpoint metadata + blobs: + items: + $ref: '#/components/schemas/BlobData' + type: array + title: Channel blob data + type: object + required: + - thread_id + - checkpoint_id + - checkpoint + title: PutCheckpointRequest + PutCheckpointResponse: + properties: + thread_id: + type: string + title: Thread Id + checkpoint_ns: + type: string + title: Checkpoint Ns + checkpoint_id: + type: string + title: Checkpoint Id + type: object + required: + - thread_id + - checkpoint_ns + - checkpoint_id + title: PutCheckpointResponse + PutWritesRequest: + properties: + thread_id: + type: string + title: Thread ID + checkpoint_ns: + type: string + title: Checkpoint namespace + default: '' + checkpoint_id: + type: string + title: Checkpoint ID + writes: + items: + $ref: '#/components/schemas/WriteData' + type: array + title: Write data + upsert: + type: boolean + title: Upsert mode + default: false + type: object + required: + - thread_id + - checkpoint_id + - writes + title: PutWritesRequest + ReasoningContent: + properties: + type: + type: string + const: reasoning + title: Type + description: The type of the message, in this case `reasoning`. + default: reasoning + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + summary: + items: + type: string + type: array + title: Summary + description: A list of short reasoning summaries + content: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Content + description: The reasoning content or chain-of-thought text + type: object + required: + - author + - summary + title: ReasoningContent + ReasoningContentDelta: + properties: + type: + type: string + const: reasoning_content + title: Type + default: reasoning_content + content_index: + type: integer + title: Content Index + content_delta: + anyOf: + - type: string + - type: 'null' + title: Content Delta + default: '' + type: object + required: + - content_index + title: ReasoningContentDelta + description: Delta for reasoning content updates + ReasoningContentEntity: + properties: + type: + type: string + const: reasoning + title: Type + description: The type of the message, in this case `reasoning`. + default: reasoning + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + summary: + items: + type: string + type: array + title: Summary + description: A list of short reasoning summaries + content: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Content + description: The reasoning content or chain-of-thought text + type: object + required: + - author + - summary + title: ReasoningContentEntity + ReasoningSummaryDelta: + properties: + type: + type: string + const: reasoning_summary + title: Type + default: reasoning_summary + summary_index: + type: integer + title: Summary Index + summary_delta: + anyOf: + - type: string + - type: 'null' + title: Summary Delta + default: '' + type: object + required: + - summary_index + title: ReasoningSummaryDelta + description: Delta for reasoning summary updates + RegisterAgentRequest: + properties: + name: + type: string + pattern: ^[a-z0-9-]+$ + title: Name + description: The unique name of the agent. + description: + type: string + title: Description + description: The description of the agent. + acp_url: + type: string + title: Acp Url + description: The URL of the ACP server for the agent. + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + description: Optional agent ID if the agent already exists and needs to + be updated. + acp_type: + $ref: '#/components/schemas/ACPType' + description: The type of ACP to use for the agent. + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: The metadata for the agent's registration. + agent_input_type: + anyOf: + - $ref: '#/components/schemas/AgentInputType' + - type: 'null' + description: The type of input the agent expects. + type: object + required: + - name + - description + - acp_url + - acp_type + title: RegisterAgentRequest + RegisterAgentResponse: + properties: + id: + type: string + title: Id + description: The unique identifier of the agent. + name: + type: string + title: Name + description: The unique name of the agent. + description: + type: string + title: Description + description: The description of the action. + status: + $ref: '#/components/schemas/AgentStatus' + description: The status of the action, indicating if it's building, ready, + failed, etc. + default: Unknown + acp_type: + $ref: '#/components/schemas/ACPType' + description: The type of the ACP Server (Either sync or async) + status_reason: + anyOf: + - type: string + - type: 'null' + title: Status Reason + description: The reason for the status of the action. + created_at: + type: string + format: date-time + title: Created At + description: The timestamp when the agent was created + updated_at: + type: string + format: date-time + title: Updated At + description: The timestamp when the agent was last updated + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: The metadata for the agent's registration. + registered_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Registered At + description: The timestamp when the agent was last registered + agent_input_type: + anyOf: + - $ref: '#/components/schemas/AgentInputType' + - type: 'null' + description: The type of input the agent expects. + production_deployment_id: + anyOf: + - type: string + - type: 'null' + title: Production Deployment Id + description: ID of the current production deployment. + agent_api_key: + anyOf: + - type: string + - type: 'null' + title: Agent Api Key + description: The API key for the agent, if applicable. + type: object + required: + - id + - name + - description + - acp_type + - created_at + - updated_at + title: RegisterAgentResponse + description: Response model for registering an agent. + RegisterBuildRequest: + properties: + name: + type: string + pattern: ^[a-z0-9-]+$ + title: Name + description: The unique name of the agent. + description: + type: string + title: Description + description: The description of the agent. + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: The metadata for the agent's build registration. + agent_input_type: + anyOf: + - $ref: '#/components/schemas/AgentInputType' + - type: 'null' + description: The type of input the agent expects. + type: object + required: + - name + - description + title: RegisterBuildRequest + description: 'Request model for registering an agent at build time (pre-deploy). + + + Unlike RegisterAgentRequest, there is no acp_url (the agent is not running + + yet) and no acp_type is required. The created agent is left in BUILD_ONLY + + status so it can be permissioned/shared before it is deployed.' + RehydrateTaskRequest: + properties: + task_id: + type: string + title: Task Id + messages: + items: + $ref: '#/components/schemas/TaskMessageEntity' + type: array + title: Messages + task_states: + items: + $ref: '#/components/schemas/StateEntity' + type: array + title: Task States + snapshot_url: + anyOf: + - type: string + maxLength: 2083 + minLength: 1 + format: uri + - type: 'null' + title: Snapshot Url + description: Presigned GET URL whose body is a JSON-encoded TaskSnapshotEntity. + Must be https; must resolve to a public address. When set, messages/task_states + must be empty. + type: object + required: + - task_id + title: RehydrateTaskRequest + description: 'Either provide inline content (messages + task_states) or a snapshot_url + + pointing at a presigned JSON download. Mixing both is rejected. + + + The inline form is the canonical shape used by export''s GET response, so + + snapshot → clean → rehydrate round-trips cleanly without serialization + + changes.' + ScheduleActionInfo: + properties: + workflow_name: + type: string + title: Workflow Name + description: Name of the workflow being executed + workflow_id_prefix: + type: string + title: Workflow ID Prefix + description: Prefix for workflow execution IDs + task_queue: + type: string + title: Task Queue + description: Task queue for the workflow + workflow_params: + anyOf: + - items: {} + type: array + - type: 'null' + title: Workflow Parameters + description: Parameters passed to the workflow + type: object + required: + - workflow_name + - workflow_id_prefix + - task_queue + title: ScheduleActionInfo + description: Information about the scheduled action + ScheduleListItem: + properties: + schedule_id: + type: string + title: Schedule ID + description: Unique identifier for the schedule + name: + type: string + title: Schedule Name + description: Human-readable name for the schedule + agent_id: + type: string + title: Agent ID + description: ID of the agent this schedule belongs to + state: + $ref: '#/components/schemas/ScheduleState' + title: State + description: Current state of the schedule + workflow_name: + anyOf: + - type: string + - type: 'null' + title: Workflow Name + description: Name of the scheduled workflow + next_action_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Next Action Time + description: Next scheduled execution time + type: object + required: + - schedule_id + - name + - agent_id + - state + title: ScheduleListItem + description: Abbreviated schedule info for list responses + ScheduleListResponse: + properties: + schedules: + items: + $ref: '#/components/schemas/ScheduleListItem' + type: array + title: Schedules + description: List of schedules + total: + type: integer + title: Total + description: Total number of schedules + type: object + required: + - schedules + - total + title: ScheduleListResponse + description: Response model for listing schedules + ScheduleResponse: + properties: + schedule_id: + type: string + title: Schedule ID + description: Unique identifier for the schedule + name: + type: string + title: Schedule Name + description: Human-readable name for the schedule + agent_id: + type: string + title: Agent ID + description: ID of the agent this schedule belongs to + state: + $ref: '#/components/schemas/ScheduleState' + title: State + description: Current state of the schedule + action: + $ref: '#/components/schemas/ScheduleActionInfo' + title: Action + spec: + $ref: '#/components/schemas/ScheduleSpecInfo' + title: Spec + description: Schedule specification + num_actions_taken: + type: integer + title: Number of Actions Taken + description: Number of times the schedule has executed + default: 0 + num_actions_missed: + type: integer + title: Number of Actions Missed + description: Number of scheduled executions that were missed + default: 0 + next_action_times: + items: + type: string + format: date-time + type: array + title: Next Action Times + description: Upcoming scheduled execution times + last_action_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Last Action Time + description: When the schedule last executed + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: When the schedule was created + type: object + required: + - schedule_id + - name + - agent_id + - state + - action + - spec + title: ScheduleResponse + description: Response model for schedule operations + ScheduleSpecInfo: + properties: + cron_expressions: + items: + type: string + type: array + title: Cron Expressions + description: Cron expressions for the schedule + intervals_seconds: + items: + type: integer + type: array + title: Interval Seconds + description: Interval specifications in seconds + start_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Start At + description: When the schedule starts being active + end_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: End At + description: When the schedule stops being active + type: object + title: ScheduleSpecInfo + description: Information about the schedule specification + ScheduleState: + type: string + enum: + - ACTIVE + - PAUSED + title: ScheduleState + description: Schedule state enum + SendEventRequest: + properties: + task_id: + anyOf: + - type: string + - type: 'null' + title: Task Id + description: The ID of the task that the event was sent to + task_name: + anyOf: + - type: string + - type: 'null' + title: Task Name + description: The name of the task that the event was sent to + content: + anyOf: + - $ref: '#/components/schemas/TaskMessageContent' + - type: 'null' + description: The content to send to the event + type: object + title: SendEventRequest + SendMessageRequest: + properties: + task_id: + anyOf: + - type: string + - type: 'null' + title: Task Id + description: The ID of the task that the message was sent to + task_name: + anyOf: + - type: string + - type: 'null' + title: Task Name + description: The name of the task that the message was sent to + content: + $ref: '#/components/schemas/TaskMessageContent' + description: The message that was sent to the agent + stream: + type: boolean + title: Stream + description: Whether to stream the response message back to the client + default: false + task_params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task Params + description: The parameters for the task (only used when creating new tasks) + type: object + required: + - content + title: SendMessageRequest + Span: + properties: + id: + type: string + title: Unique Span ID + trace_id: + type: string + title: The trace ID for this span + description: Unique identifier for the trace this span belongs to + task_id: + anyOf: + - type: string + - type: 'null' + title: The task ID this span is associated with + description: ID of the task this span belongs to + parent_id: + anyOf: + - type: string + - type: 'null' + title: The parent span ID if this is a child span + description: ID of the parent span if this is a child span in a trace + name: + type: string + title: The name of the span + description: Name that describes what operation this span represents + start_time: + type: string + format: date-time + title: The start time of the span + description: The time the span started + end_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The end time of the span + description: The time the span ended + input: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The input data for the span + description: Input parameters or data for the operation + output: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The output data from the span + description: Output data resulting from the operation + data: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: Additional data associated with the span + description: Any additional metadata or context for the span + type: object + required: + - id + - trace_id + - name + - start_time + title: Span + State: + properties: + task_id: + type: string + title: The unique id of the task to send the state to + agent_id: + type: string + title: The unique id of the agent to send the state to + state: + additionalProperties: true + type: object + title: The state to send to the task. + id: + type: string + title: Id + description: The task state's unique id + created_at: + type: string + format: date-time + title: Created At + description: The timestamp when the state was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: The timestamp when the state was last updated + type: object + required: + - task_id + - agent_id + - state + - id + - created_at + title: State + description: 'Represents a state in the agent system. A state is associated + uniquely with a task and an agent. + + + This entity is used to store states in MongoDB, with each state + + associated with a specific task and agent. The combination of task_id and + agent_id is globally unique. + + + The state is a dictionary of arbitrary data.' + StateEntity: + properties: + id: + anyOf: + - type: string + - type: 'null' + title: Id + description: The task state's unique id + task_id: + type: string + title: Task Id + description: ID of the task this state belongs to. The combination of task_id + and agent_id is globally unique. + agent_id: + type: string + title: Agent Id + description: ID of the agent this state belongs to. The combination of task_id + and agent_id is globally unique. + state: + additionalProperties: true + type: object + title: State + description: The state object that contains arbitrary data + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: The timestamp when the state was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: The timestamp when the state was last updated + type: object + required: + - task_id + - agent_id + - state + title: StateEntity + description: 'Represents a state in the agent system. A state is associated + uniquely with a task and an agent. + + + This entity is used to store states in MongoDB, with each state + + associated with a specific task and agent. The combination of task_id and + agent_id is globally unique. + + + The state is a dictionary of arbitrary data.' + StreamTaskMessageDelta: + properties: + type: + type: string + const: delta + title: Type + default: delta + index: + anyOf: + - type: integer + - type: 'null' + title: Index + parent_task_message: + anyOf: + - $ref: '#/components/schemas/TaskMessage' + - type: 'null' + delta: + anyOf: + - $ref: '#/components/schemas/TaskMessageDelta' + - type: 'null' + type: object + title: StreamTaskMessageDelta + description: Event for streaming chunks of content + StreamTaskMessageDone: + properties: + type: + type: string + const: done + title: Type + default: done + index: + anyOf: + - type: integer + - type: 'null' + title: Index + parent_task_message: + anyOf: + - $ref: '#/components/schemas/TaskMessage' + - type: 'null' + type: object + title: StreamTaskMessageDone + description: Event for indicating the task is done + StreamTaskMessageFull: + properties: + type: + type: string + const: full + title: Type + default: full + index: + anyOf: + - type: integer + - type: 'null' + title: Index + parent_task_message: + anyOf: + - $ref: '#/components/schemas/TaskMessage' + - type: 'null' + content: + $ref: '#/components/schemas/TaskMessageContent' + type: object + required: + - content + title: StreamTaskMessageFull + description: Event for streaming the full content + StreamTaskMessageStart: + properties: + type: + type: string + const: start + title: Type + default: start + index: + anyOf: + - type: integer + - type: 'null' + title: Index + parent_task_message: + anyOf: + - $ref: '#/components/schemas/TaskMessage' + - type: 'null' + content: + $ref: '#/components/schemas/TaskMessageContent' + type: object + required: + - content + title: StreamTaskMessageStart + description: Event for starting a streaming message + Task: + properties: + id: + type: string + title: Unique Task ID + name: + anyOf: + - type: string + - type: 'null' + title: Unique name of the task + status: + anyOf: + - $ref: '#/components/schemas/TaskStatus' + - type: 'null' + title: The current status of the task + status_reason: + anyOf: + - type: string + - type: 'null' + title: The reason for the current task status + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task was last updated + cleaned_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task's content was cleaned for retention compliance; + null when active + params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task parameters + task_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task metadata + type: object + required: + - id + title: Task + TaskMessage: + properties: + id: + anyOf: + - type: string + - type: 'null' + title: Id + description: The task message's unique id + task_id: + type: string + title: Task Id + description: ID of the task this message belongs to + content: + $ref: '#/components/schemas/TaskMessageContent' + description: The content of the message. This content is not OpenAI compatible. + These are messages that are meant to be displayed to the user. + streaming_status: + anyOf: + - type: string + enum: + - IN_PROGRESS + - DONE + - type: 'null' + title: In case of streaming, this indicates whether the message is still + being streamed or has been completed + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: The timestamp when the message was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: The timestamp when the message was last updated + type: object + required: + - task_id + - content + title: TaskMessage + description: 'Represents a message in the agent system. + + + This entity is used to store messages in MongoDB, with each message + + associated with a specific task.' + TaskMessageContent: + oneOf: + - $ref: '#/components/schemas/TextContent' + - $ref: '#/components/schemas/ReasoningContent' + - $ref: '#/components/schemas/DataContent' + - $ref: '#/components/schemas/ToolRequestContent' + - $ref: '#/components/schemas/ToolResponseContent' + title: TaskMessageContent + discriminator: + propertyName: type + mapping: + data: '#/components/schemas/DataContent' + reasoning: '#/components/schemas/ReasoningContent' + text: '#/components/schemas/TextContent' + tool_request: '#/components/schemas/ToolRequestContent' + tool_response: '#/components/schemas/ToolResponseContent' + TaskMessageDelta: + oneOf: + - $ref: '#/components/schemas/TextDelta' + - $ref: '#/components/schemas/DataDelta' + - $ref: '#/components/schemas/ToolRequestDelta' + - $ref: '#/components/schemas/ToolResponseDelta' + - $ref: '#/components/schemas/ReasoningSummaryDelta' + - $ref: '#/components/schemas/ReasoningContentDelta' + title: TaskMessageDelta + discriminator: + propertyName: type + mapping: + data: '#/components/schemas/DataDelta' + reasoning_content: '#/components/schemas/ReasoningContentDelta' + reasoning_summary: '#/components/schemas/ReasoningSummaryDelta' + text: '#/components/schemas/TextDelta' + tool_request: '#/components/schemas/ToolRequestDelta' + tool_response: '#/components/schemas/ToolResponseDelta' + TaskMessageEntity: + properties: + id: + anyOf: + - type: string + - type: 'null' + title: Id + description: The task message's unique id + task_id: + type: string + title: Task Id + description: ID of the task this message belongs to + content: + oneOf: + - $ref: '#/components/schemas/TextContentEntity' + - $ref: '#/components/schemas/DataContentEntity' + - $ref: '#/components/schemas/ToolRequestContentEntity' + - $ref: '#/components/schemas/ToolResponseContentEntity' + - $ref: '#/components/schemas/ReasoningContentEntity' + title: Content + description: The content of the message. This content is not OpenAI compatible. + These are messages that are meant to be displayed to the user. + discriminator: + propertyName: type + mapping: + data: '#/components/schemas/DataContentEntity' + reasoning: '#/components/schemas/ReasoningContentEntity' + text: '#/components/schemas/TextContentEntity' + tool_request: '#/components/schemas/ToolRequestContentEntity' + tool_response: '#/components/schemas/ToolResponseContentEntity' + streaming_status: + anyOf: + - type: string + enum: + - IN_PROGRESS + - DONE + - type: 'null' + title: In case of streaming, this indicates whether the message is still + being streamed or has been completed + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: The timestamp when the message was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: The timestamp when the message was last updated + type: object + required: + - task_id + - content + title: TaskMessageEntity + description: 'Represents a message in the agent system. + + + This entity is used to store messages in MongoDB, with each message + + associated with a specific task.' + TaskMessageUpdate: + oneOf: + - $ref: '#/components/schemas/StreamTaskMessageStart' + - $ref: '#/components/schemas/StreamTaskMessageDelta' + - $ref: '#/components/schemas/StreamTaskMessageFull' + - $ref: '#/components/schemas/StreamTaskMessageDone' + title: TaskMessageUpdate + discriminator: + propertyName: type + mapping: + delta: '#/components/schemas/StreamTaskMessageDelta' + done: '#/components/schemas/StreamTaskMessageDone' + full: '#/components/schemas/StreamTaskMessageFull' + start: '#/components/schemas/StreamTaskMessageStart' + TaskRelationships: + type: string + enum: + - agents + title: TaskRelationships + description: Task relationships that can be loaded + TaskResponse: + properties: + id: + type: string + title: Unique Task ID + name: + anyOf: + - type: string + - type: 'null' + title: Unique name of the task + status: + anyOf: + - $ref: '#/components/schemas/TaskStatus' + - type: 'null' + title: The current status of the task + status_reason: + anyOf: + - type: string + - type: 'null' + title: The reason for the current task status + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task was last updated + cleaned_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task's content was cleaned for retention compliance; + null when active + params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task parameters + task_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task metadata + agents: + anyOf: + - items: + $ref: '#/components/schemas/Agent' + type: array + - type: 'null' + title: Agents associated with this task (only populated when 'agent' view + is requested) + type: object + required: + - id + title: TaskResponse + description: Task response model with optional related data based on relationships + TaskStatus: + type: string + enum: + - CANCELED + - COMPLETED + - FAILED + - RUNNING + - TERMINATED + - TIMED_OUT + - DELETED + title: TaskStatus + TaskStatusReasonRequest: + properties: + reason: + anyOf: + - type: string + - type: 'null' + title: Optional reason for the status change + type: object + title: TaskStatusReasonRequest + TextContent: + properties: + type: + type: string + const: text + title: Type + description: The type of the message, in this case `text`. + default: text + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + format: + $ref: '#/components/schemas/TextFormat' + description: The format of the message. This is used by the client to determine + how to display the message. + default: plain + content: + type: string + title: Content + description: The contents of the text message. + attachments: + anyOf: + - items: + $ref: '#/components/schemas/FileAttachment' + type: array + - type: 'null' + title: Attachments + description: Optional list of file attachments with structured metadata. + type: object + required: + - author + - content + title: TextContent + TextContentEntity: + properties: + type: + type: string + const: text + title: Type + description: The type of the message, in this case `text`. + default: text + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + format: + $ref: '#/components/schemas/TextFormat' + description: The format of the message. This is used by the client to determine + how to display the message. + default: plain + content: + type: string + title: Content + description: The contents of the text message. + attachments: + anyOf: + - items: + $ref: '#/components/schemas/FileAttachmentEntity' + type: array + - type: 'null' + title: Attachments + description: Optional list of file attachments with structured metadata. + type: object + required: + - author + - content + title: TextContentEntity + TextDelta: + properties: + type: + type: string + const: text + title: Type + default: text + text_delta: + anyOf: + - type: string + - type: 'null' + title: Text Delta + default: '' + type: object + title: TextDelta + description: Delta for text updates + TextFormat: + type: string + enum: + - markdown + - plain + - code + title: TextFormat + ToolRequestContent: + properties: + type: + type: string + const: tool_request + title: Type + description: The type of the message, in this case `tool_request`. + default: tool_request + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + tool_call_id: + type: string + title: Tool Call Id + description: The ID of the tool call that is being requested. + name: + type: string + title: Name + description: The name of the tool that is being requested. + arguments: + additionalProperties: true + type: object + title: Arguments + description: The arguments to the tool. + type: object + required: + - author + - tool_call_id + - name + - arguments + title: ToolRequestContent + ToolRequestContentEntity: + properties: + type: + type: string + const: tool_request + title: Type + description: The type of the message, in this case `tool_request`. + default: tool_request + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + tool_call_id: + type: string + title: Tool Call Id + description: The ID of the tool call that is being requested. + name: + type: string + title: Name + description: The name of the tool that is being requested. + arguments: + additionalProperties: true + type: object + title: Arguments + description: The arguments to the tool. + type: object + required: + - author + - tool_call_id + - name + - arguments + title: ToolRequestContentEntity + ToolRequestDelta: + properties: + type: + type: string + const: tool_request + title: Type + default: tool_request + tool_call_id: + type: string + title: Tool Call Id + name: + type: string + title: Name + arguments_delta: + anyOf: + - type: string + - type: 'null' + title: Arguments Delta + default: '' + type: object + required: + - tool_call_id + - name + title: ToolRequestDelta + description: Delta for tool request updates + ToolResponseContent: + properties: + type: + type: string + const: tool_response + title: Type + description: The type of the message, in this case `tool_response`. + default: tool_response + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + tool_call_id: + type: string + title: Tool Call Id + description: The ID of the tool call that is being responded to. + name: + type: string + title: Name + description: The name of the tool that is being responded to. + content: + title: Content + description: The result of the tool. + type: object + required: + - author + - tool_call_id + - name + - content + title: ToolResponseContent + ToolResponseContentEntity: + properties: + type: + type: string + const: tool_response + title: Type + description: The type of the message, in this case `tool_response`. + default: tool_response + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + tool_call_id: + type: string + title: Tool Call Id + description: The ID of the tool call that is being responded to. + name: + type: string + title: Name + description: The name of the tool that is being responded to. + content: + title: Content + description: The result of the tool. + type: object + required: + - author + - tool_call_id + - name + - content + title: ToolResponseContentEntity + ToolResponseDelta: + properties: + type: + type: string + const: tool_response + title: Type + default: tool_response + tool_call_id: + type: string + title: Tool Call Id + name: + type: string + title: Name + content_delta: + anyOf: + - type: string + - type: 'null' + title: Content Delta + default: '' + type: object + required: + - tool_call_id + - name + title: ToolResponseDelta + description: Delta for tool response updates + UnpauseScheduleRequest: + properties: + note: + anyOf: + - type: string + - type: 'null' + title: Note + description: Optional note explaining why the schedule was unpaused + type: object + title: UnpauseScheduleRequest + description: Request model for unpausing a schedule + UpdateAgentTaskTrackerRequest: + properties: + last_processed_event_id: + anyOf: + - type: string + - type: 'null' + title: Last Processed Event Id + description: The most recent processed event ID (omit to leave unchanged) + status: + anyOf: + - type: string + - type: 'null' + title: Status + description: Processing status + status_reason: + anyOf: + - type: string + - type: 'null' + title: Status Reason + description: Optional status reason + type: object + title: UpdateAgentTaskTrackerRequest + description: Request model for updating an agent task tracker. + UpdateSpanRequest: + properties: + trace_id: + anyOf: + - type: string + - type: 'null' + title: The trace ID for this span + description: Unique identifier for the trace this span belongs to + task_id: + anyOf: + - type: string + - type: 'null' + title: The task ID this span is associated with + description: ID of the task this span belongs to + parent_id: + anyOf: + - type: string + - type: 'null' + title: The parent span ID if this is a child span + description: ID of the parent span if this is a child span in a trace + name: + anyOf: + - type: string + - type: 'null' + title: The name of the span + description: Name that describes what operation this span represents + start_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The start time of the span + description: The time the span started + end_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The end time of the span + description: The time the span ended + input: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The input data for the span + description: Input parameters or data for the operation + output: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The output data from the span + description: Output data resulting from the operation + data: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: Additional data associated with the span + description: Any additional metadata or context for the span + type: object + title: UpdateSpanRequest + UpdateStateRequest: + properties: + state: + additionalProperties: true + type: object + title: The state to update the state with. + type: object + required: + - state + title: UpdateStateRequest + UpdateTaskMessageRequest: + properties: + task_id: + type: string + title: The unique id of the task to update the message of + content: + $ref: '#/components/schemas/TaskMessageContent' + title: The message to update the message with. + streaming_status: + anyOf: + - type: string + enum: + - IN_PROGRESS + - DONE + - type: 'null' + title: The streaming status of the message + type: object + required: + - task_id + - content + title: UpdateTaskMessageRequest + UpdateTaskRequest: + properties: + task_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: If provided, replaces task_metadata with this value + type: object + title: UpdateTaskRequest + ValidationError: + properties: + loc: + items: + anyOf: + - type: string + - type: integer + type: array + title: Location + msg: + type: string + title: Message + type: + type: string + title: Error Type + input: + title: Input + ctx: + type: object + title: Context + type: object + required: + - loc + - msg + - type + title: ValidationError + WriteData: + properties: + task_id: + type: string + title: Task ID + idx: + type: integer + title: Write index + channel: + type: string + title: Channel name + type: + anyOf: + - type: string + - type: 'null' + title: Serialization type tag + blob: + type: string + title: Base64-encoded binary data + task_path: + type: string + title: Task path + default: '' + type: object + required: + - task_id + - idx + - channel + - blob + title: WriteData + WriteResponse: + properties: + task_id: + type: string + title: Task Id + idx: + type: integer + title: Idx + channel: + type: string + title: Channel + type: + anyOf: + - type: string + - type: 'null' + title: Type + blob: + anyOf: + - type: string + - type: 'null' + title: Blob + type: object + required: + - task_id + - idx + - channel + title: WriteResponse diff --git a/tests/compat/server_specs/manifest.json b/tests/compat/server_specs/manifest.json new file mode 100644 index 000000000..986650583 --- /dev/null +++ b/tests/compat/server_specs/manifest.json @@ -0,0 +1,19 @@ +{ + "description": "Supported server OpenAPI contract window for SDK request-compatibility. Each file is agentex/openapi.yaml from scaleapi/scale-agentex at the pinned sha. Advance 'min-supported' as the oldest deployed server moves forward, then run refresh_specs.py.", + "source_repo": "scaleapi/scale-agentex", + "source_path": "agentex/openapi.yaml", + "specs": [ + { + "label": "current", + "file": "current.yaml", + "sha": "ab469df91bba043ea25356c89147d29f7df03bad", + "note": "scale-agentex main at vendoring time" + }, + { + "label": "min-supported", + "file": "min-supported.yaml", + "sha": "39e3a7118d55b7db4c01f6ee14e68a8167bb001d", + "note": "pre-#278; oldest contract still in the field. UpdateStateRequest requires task_id/agent_id in the body — the contract the 0.13.0 client broke." + } + ] +} diff --git a/tests/compat/server_specs/min-supported.yaml b/tests/compat/server_specs/min-supported.yaml new file mode 100644 index 000000000..cbcf2ca45 --- /dev/null +++ b/tests/compat/server_specs/min-supported.yaml @@ -0,0 +1,6761 @@ +openapi: 3.1.0 +info: + title: Agentex API + version: 0.1.0 +paths: + /agents/{agent_id}: + get: + tags: + - Agents + summary: Get Agent by ID + description: Get an agent by its unique ID. + operationId: get_agent_by_id_agents__agent_id__get + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Agents + summary: Delete Agent by ID + description: Delete an agent by its unique ID. + operationId: delete_agent_by_id_agents__agent_id__delete + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/name/{agent_name}: + get: + tags: + - Agents + summary: Get Agent by Name + description: Get an agent by its unique name. + operationId: get_agent_by_name_agents_name__agent_name__get + parameters: + - name: agent_name + in: path + required: true + schema: + type: string + title: Agent Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Agents + summary: Delete Agent by Name + description: Delete an agent by its unique name. + operationId: delete_agent_by_name_agents_name__agent_name__delete + parameters: + - name: agent_name + in: path + required: true + schema: + type: string + title: Agent Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents: + get: + tags: + - Agents + summary: List Agents + description: List all registered agents, optionally filtered by query parameters. + operationId: list_agents_agents_get + parameters: + - name: task_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Task ID + title: Task Id + description: Task ID + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + description: Limit + default: 50 + title: Limit + description: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + description: Page number + default: 1 + title: Page Number + description: Page number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Field to order by + title: Order By + description: Field to order by + - name: order_direction + in: query + required: false + schema: + type: string + description: Order direction (asc or desc) + default: desc + title: Order Direction + description: Order direction (asc or desc) + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Agent' + title: Response List Agents Agents Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/register: + post: + tags: + - Agents + summary: Register Agent + description: Register a new agent or update an existing one. + operationId: register_agent_agents_register_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterAgentRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterAgentResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/register-build: + post: + tags: + - Agents + summary: Register Build + description: Register an agent at build time, before it is deployed, so it can + be permissioned and shared prior to deploy. Idempotent by name. + operationId: register_build_agents_register_build_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/RegisterBuildRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Agent' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/forward/name/{agent_name}/{path}: + get: + tags: + - Agents + summary: Forward GET request to agent by name + description: Forward a GET request to an agent by its name. + operationId: forward_get_request_to_agent_agents_forward_name__agent_name___path__get + parameters: + - name: agent_name + in: path + required: true + schema: + type: string + title: Agent Name + - name: path + in: path + required: true + schema: + type: string + title: Path + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + post: + tags: + - Agents + summary: Forward POST request to agent by name + description: Forward a POST request to an agent by its name. + operationId: forward_post_request_to_agent_agents_forward_name__agent_name___path__post + parameters: + - name: agent_name + in: path + required: true + schema: + type: string + title: Agent Name + - name: path + in: path + required: true + schema: + type: string + title: Path + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/rpc: + post: + tags: + - Agents + summary: Handle Agent RPC by ID + description: Handle JSON-RPC requests for an agent by its unique ID. + operationId: handle_agent_rpc_by_id_agents__agent_id__rpc_post + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/name/{agent_name}/rpc: + post: + tags: + - Agents + summary: Handle Agent RPC by Name + description: Handle JSON-RPC requests for an agent by its unique name. + operationId: handle_agent_rpc_by_name_agents_name__agent_name__rpc_post + parameters: + - name: agent_name + in: path + required: true + schema: + type: string + title: Agent Name + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}: + get: + tags: + - Tasks + summary: Get Task by ID + description: Get a task by its unique ID. + operationId: get_task_tasks__task_id__get + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + - name: relationships + in: query + required: false + schema: + type: array + items: + $ref: '#/components/schemas/TaskRelationships' + title: Relationships + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TaskResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Tasks + summary: Delete Task by ID + description: Delete a task by its unique ID. + operationId: delete_task_tasks__task_id__delete + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + tags: + - Tasks + summary: Update Task by ID + description: Update mutable fields for a task by its unique ID. + operationId: update_task_tasks__task_id__put + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateTaskRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/name/{task_name}: + get: + tags: + - Tasks + summary: Get Task by Name + description: Get a task by its unique name. + operationId: get_task_by_name_tasks_name__task_name__get + parameters: + - name: task_name + in: path + required: true + schema: + type: string + title: Task Name + - name: relationships + in: query + required: false + schema: + type: array + items: + $ref: '#/components/schemas/TaskRelationships' + title: Relationships + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TaskResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Tasks + summary: Delete Task by Name + description: Delete a task by its unique name. + operationId: delete_task_by_name_tasks_name__task_name__delete + parameters: + - name: task_name + in: path + required: true + schema: + type: string + title: Task Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + tags: + - Tasks + summary: Update Task by Name + description: Update mutable fields for a task by its unique Name. + operationId: update_task_by_name_tasks_name__task_name__put + parameters: + - name: task_name + in: path + required: true + schema: + type: string + title: Task Name + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateTaskRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks: + get: + tags: + - Tasks + summary: List Tasks + description: List all tasks. + operationId: list_tasks_tasks_get + parameters: + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: agent_name + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Name + - name: status + in: query + required: false + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatus' + - type: 'null' + description: Filter tasks by status (e.g. RUNNING, COMPLETED). + title: Status + description: Filter tasks by status (e.g. RUNNING, COMPLETED). + - name: task_metadata + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: 'JSON-encoded object used to filter tasks via JSONB containment. + Example: {"created_by_user_id": "abc-123"}.' + title: Task Metadata + description: 'JSON-encoded object used to filter tasks via JSONB containment. + Example: {"created_by_user_id": "abc-123"}.' + - name: limit + in: query + required: false + schema: + type: integer + default: 50 + title: Limit + - name: page_number + in: query + required: false + schema: + type: integer + default: 1 + title: Page Number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Order By + - name: order_direction + in: query + required: false + schema: + type: string + default: desc + title: Order Direction + - name: relationships + in: query + required: false + schema: + type: array + items: + $ref: '#/components/schemas/TaskRelationships' + title: Relationships + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/TaskResponse' + title: Response List Tasks Tasks Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/complete: + post: + tags: + - Tasks + summary: Complete Task + description: Mark a running task as completed. + operationId: complete_task_tasks__task_id__complete_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatusReasonRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/fail: + post: + tags: + - Tasks + summary: Fail Task + description: Mark a running task as failed. + operationId: fail_task_tasks__task_id__fail_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatusReasonRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/cancel: + post: + tags: + - Tasks + summary: Cancel Task + description: Mark a running task as canceled. + operationId: cancel_task_tasks__task_id__cancel_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatusReasonRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/terminate: + post: + tags: + - Tasks + summary: Terminate Task + description: Mark a running task as terminated. + operationId: terminate_task_tasks__task_id__terminate_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatusReasonRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/timeout: + post: + tags: + - Tasks + summary: Timeout Task + description: Mark a running task as timed out. + operationId: timeout_task_tasks__task_id__timeout_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/TaskStatusReasonRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Task' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/stream: + get: + tags: + - Tasks + summary: Stream Task Events by ID + description: Stream events for a task by its unique ID. + operationId: stream_task_events_tasks__task_id__stream_get + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/name/{task_name}/stream: + get: + tags: + - Tasks + summary: Stream Task Events by Name + description: Stream events for a task by its unique name. + operationId: stream_task_events_by_name_tasks_name__task_name__stream_get + parameters: + - name: task_name + in: path + required: true + schema: + type: string + title: Task Name + responses: + '200': + description: Successful Response + content: + application/json: + schema: {} + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/query/{query_name}: + get: + tags: + - Tasks + summary: Query Task Workflow + description: Query a Temporal workflow associated with a task for its current + state. + operationId: query_task_workflow_tasks__task_id__query__query_name__get + parameters: + - name: query_name + in: path + required: true + schema: + type: string + title: Query Name + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: object + additionalProperties: true + title: Response Query Task Workflow Tasks Task Id Query Query Name Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /messages/batch: + put: + tags: + - Messages + summary: Batch Update Messages + operationId: batch_update_messages_messages_batch_put + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BatchUpdateTaskMessagesRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + items: + $ref: '#/components/schemas/TaskMessage' + type: array + title: Response Batch Update Messages Messages Batch Put + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + post: + tags: + - Messages + summary: Batch Create Messages + operationId: batch_create_messages_messages_batch_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/BatchCreateTaskMessagesRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + items: + $ref: '#/components/schemas/TaskMessage' + type: array + title: Response Batch Create Messages Messages Batch Post + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /messages: + post: + tags: + - Messages + summary: Create Message + operationId: create_message_messages_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateTaskMessageRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TaskMessage' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Messages + summary: List Messages + description: 'List messages for a task with offset-based pagination. + + + For cursor-based pagination with infinite scroll support, use /messages/paginated.' + operationId: list_messages_messages_get + parameters: + - name: limit + in: query + required: false + schema: + type: integer + default: 50 + title: Limit + - name: page_number + in: query + required: false + schema: + type: integer + default: 1 + title: Page Number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Order By + - name: order_direction + in: query + required: false + schema: + type: string + default: desc + title: Order Direction + - name: filters + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: "JSON-encoded array of TaskMessageEntityFilter objects.\n\n\ + Schema: {\n \"$defs\": {\n \"DataContentEntityOptional\": {\n \ + \ \"properties\": {\n \"type\": {\n \"anyOf\": [\n \ + \ {\n \"const\": \"data\",\n \"type\"\ + : \"string\"\n },\n {\n \"type\": \"\ + null\"\n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The type of the message, in this case `data`.\"\ + ,\n \"title\": \"Type\"\n },\n \"author\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"data\"\ + : {\n \"anyOf\": [\n {\n \"additionalProperties\"\ + : true,\n \"type\": \"object\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The contents\ + \ of the data message.\",\n \"title\": \"Data\"\n }\n\ + \ },\n \"title\": \"DataContentEntityOptional\",\n \"type\"\ + : \"object\"\n },\n \"FileAttachmentEntity\": {\n \"description\"\ + : \"Represents a file attachment in messages.\",\n \"properties\"\ + : {\n \"file_id\": {\n \"description\": \"The unique ID\ + \ of the attached file\",\n \"title\": \"File Id\",\n \ + \ \"type\": \"string\"\n },\n \"name\": {\n \"\ + description\": \"The name of the file\",\n \"title\": \"Name\"\ + ,\n \"type\": \"string\"\n },\n \"size\": {\n \ + \ \"description\": \"The size of the file in bytes\",\n \ + \ \"title\": \"Size\",\n \"type\": \"integer\"\n },\n\ + \ \"type\": {\n \"description\": \"The MIME type or content\ + \ type of the file\",\n \"title\": \"Type\",\n \"type\"\ + : \"string\"\n }\n },\n \"required\": [\n \"file_id\"\ + ,\n \"name\",\n \"size\",\n \"type\"\n ],\n\ + \ \"title\": \"FileAttachmentEntity\",\n \"type\": \"object\"\ + \n },\n \"MessageAuthor\": {\n \"enum\": [\n \"user\"\ + ,\n \"agent\"\n ],\n \"title\": \"MessageAuthor\",\n\ + \ \"type\": \"string\"\n },\n \"MessageStyle\": {\n \"\ + enum\": [\n \"static\",\n \"active\"\n ],\n \"\ + title\": \"MessageStyle\",\n \"type\": \"string\"\n },\n \"\ + ReasoningContentEntityOptional\": {\n \"properties\": {\n \ + \ \"type\": {\n \"anyOf\": [\n {\n \"\ + const\": \"reasoning\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `reasoning`.\",\n \"\ + title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"summary\"\ + : {\n \"anyOf\": [\n {\n \"items\": {\n\ + \ \"type\": \"string\"\n },\n \ + \ \"type\": \"array\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"A list of short reasoning summaries\"\ + ,\n \"title\": \"Summary\"\n },\n \"content\":\ + \ {\n \"anyOf\": [\n {\n \"items\": {\n\ + \ \"type\": \"string\"\n },\n \ + \ \"type\": \"array\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"The reasoning content or chain-of-thought\ + \ text\",\n \"title\": \"Content\"\n }\n },\n \ + \ \"title\": \"ReasoningContentEntityOptional\",\n \"type\": \"\ + object\"\n },\n \"TextContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"text\",\n \"type\": \"string\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The type of the message, in this case `text`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"format\"\ + : {\n \"anyOf\": [\n {\n \"$ref\": \"\ + #/$defs/TextFormat\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"The format of the message. This\ + \ is used by the client to determine how to display the message.\"\n \ + \ },\n \"content\": {\n \"anyOf\": [\n \ + \ {\n \"type\": \"string\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The contents\ + \ of the text message.\",\n \"title\": \"Content\"\n },\n\ + \ \"attachments\": {\n \"anyOf\": [\n {\n \ + \ \"items\": {\n \"$ref\": \"#/$defs/FileAttachmentEntity\"\ + \n },\n \"type\": \"array\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + Optional list of file attachments with structured metadata.\",\n \ + \ \"title\": \"Attachments\"\n }\n },\n \"title\"\ + : \"TextContentEntityOptional\",\n \"type\": \"object\"\n },\n\ + \ \"TextFormat\": {\n \"enum\": [\n \"markdown\",\n \ + \ \"plain\",\n \"code\"\n ],\n \"title\": \"TextFormat\"\ + ,\n \"type\": \"string\"\n },\n \"ToolRequestContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\"\ + : [\n {\n \"const\": \"tool_request\",\n \ + \ \"type\": \"string\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The type of the message,\ + \ in this case `tool_request`.\",\n \"title\": \"Type\"\n \ + \ },\n \"author\": {\n \"anyOf\": [\n {\n\ + \ \"$ref\": \"#/$defs/MessageAuthor\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"tool_call_id\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The ID of the tool call that is being requested.\"\ + ,\n \"title\": \"Tool Call Id\"\n },\n \"name\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The name of the tool that is being requested.\"\ + ,\n \"title\": \"Name\"\n },\n \"arguments\": {\n\ + \ \"anyOf\": [\n {\n \"additionalProperties\"\ + : true,\n \"type\": \"object\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The arguments\ + \ to the tool.\",\n \"title\": \"Arguments\"\n }\n \ + \ },\n \"title\": \"ToolRequestContentEntityOptional\",\n \ + \ \"type\": \"object\"\n },\n \"ToolResponseContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\"\ + : [\n {\n \"const\": \"tool_response\",\n \ + \ \"type\": \"string\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The type of the message,\ + \ in this case `tool_response`.\",\n \"title\": \"Type\"\n \ + \ },\n \"author\": {\n \"anyOf\": [\n \ + \ {\n \"$ref\": \"#/$defs/MessageAuthor\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"tool_call_id\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The ID of the tool call that is being responded\ + \ to.\",\n \"title\": \"Tool Call Id\"\n },\n \"\ + name\": {\n \"anyOf\": [\n {\n \"type\"\ + : \"string\"\n },\n {\n \"type\": \"\ + null\"\n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The name of the tool that is being responded\ + \ to.\",\n \"title\": \"Name\"\n },\n \"content\"\ + : {\n \"anyOf\": [\n {},\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"default\"\ + : null,\n \"description\": \"The result of the tool.\",\n \ + \ \"title\": \"Content\"\n }\n },\n \"title\":\ + \ \"ToolResponseContentEntityOptional\",\n \"type\": \"object\"\n\ + \ }\n },\n \"description\": \"Filter model for TaskMessage - all\ + \ fields optional for flexible filtering.\\n\\nThe `exclude` field determines\ + \ whether this filter is inclusionary or exclusionary.\\nWhen multiple\ + \ filters are provided:\\n- Inclusionary filters (exclude=False) are OR'd\ + \ together\\n- Exclusionary filters (exclude=True) are OR'd together and\ + \ negated with $nor\\n- The two groups are AND'd: (include1 OR include2)\ + \ AND NOT (exclude1 OR exclude2)\",\n \"properties\": {\n \"content\"\ + : {\n \"anyOf\": [\n {\n \"$ref\": \"#/$defs/ToolRequestContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/DataContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/TextContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ToolResponseContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ReasoningContentEntityOptional\"\ + \n },\n {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Filter by message\ + \ content\",\n \"title\": \"Content\"\n },\n \"streaming_status\"\ + : {\n \"anyOf\": [\n {\n \"enum\": [\n \ + \ \"IN_PROGRESS\",\n \"DONE\"\n ],\n \"\ + type\": \"string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \"description\"\ + : \"Filter by streaming status\",\n \"title\": \"Streaming Status\"\ + \n },\n \"exclude\": {\n \"default\": false,\n \"description\"\ + : \"If true, this filter excludes matching messages\",\n \"title\"\ + : \"Exclude\",\n \"type\": \"boolean\"\n }\n },\n \"title\"\ + : \"TaskMessageEntityFilter\",\n \"type\": \"object\"\n}\n\nEach filter\ + \ can include:\n- `content`: Filter by message content (type, author,\ + \ data fields)\n- `streaming_status`: Filter by status (\"IN_PROGRESS\"\ + \ or \"DONE\")\n- `exclude`: If true, excludes matching messages (default:\ + \ false)\n\nMultiple filters are combined: inclusionary filters (exclude=false)\ + \ are OR'd together,\nexclusionary filters (exclude=true) are OR'd and\ + \ negated, then both groups are AND'd.\n" + title: Filters + description: "JSON-encoded array of TaskMessageEntityFilter objects.\n\nSchema:\ + \ {\n \"$defs\": {\n \"DataContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"data\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `data`.\",\n \"title\"\ + : \"Type\"\n },\n \"author\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageAuthor\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"data\": {\n \ + \ \"anyOf\": [\n {\n \"additionalProperties\": true,\n\ + \ \"type\": \"object\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The contents of the data\ + \ message.\",\n \"title\": \"Data\"\n }\n },\n \ + \ \"title\": \"DataContentEntityOptional\",\n \"type\": \"object\"\ + \n },\n \"FileAttachmentEntity\": {\n \"description\": \"Represents\ + \ a file attachment in messages.\",\n \"properties\": {\n \"\ + file_id\": {\n \"description\": \"The unique ID of the attached\ + \ file\",\n \"title\": \"File Id\",\n \"type\": \"string\"\ + \n },\n \"name\": {\n \"description\": \"The name\ + \ of the file\",\n \"title\": \"Name\",\n \"type\": \"\ + string\"\n },\n \"size\": {\n \"description\": \"\ + The size of the file in bytes\",\n \"title\": \"Size\",\n \ + \ \"type\": \"integer\"\n },\n \"type\": {\n \ + \ \"description\": \"The MIME type or content type of the file\",\n \ + \ \"title\": \"Type\",\n \"type\": \"string\"\n }\n\ + \ },\n \"required\": [\n \"file_id\",\n \"name\"\ + ,\n \"size\",\n \"type\"\n ],\n \"title\": \"FileAttachmentEntity\"\ + ,\n \"type\": \"object\"\n },\n \"MessageAuthor\": {\n \"\ + enum\": [\n \"user\",\n \"agent\"\n ],\n \"title\"\ + : \"MessageAuthor\",\n \"type\": \"string\"\n },\n \"MessageStyle\"\ + : {\n \"enum\": [\n \"static\",\n \"active\"\n ],\n\ + \ \"title\": \"MessageStyle\",\n \"type\": \"string\"\n },\n\ + \ \"ReasoningContentEntityOptional\": {\n \"properties\": {\n \ + \ \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"reasoning\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `reasoning`.\",\n \"\ + title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"summary\": {\n \ + \ \"anyOf\": [\n {\n \"items\": {\n \ + \ \"type\": \"string\"\n },\n \"type\":\ + \ \"array\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \"\ + description\": \"A list of short reasoning summaries\",\n \"title\"\ + : \"Summary\"\n },\n \"content\": {\n \"anyOf\":\ + \ [\n {\n \"items\": {\n \"type\"\ + : \"string\"\n },\n \"type\": \"array\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The reasoning content or chain-of-thought text\",\n \"title\"\ + : \"Content\"\n }\n },\n \"title\": \"ReasoningContentEntityOptional\"\ + ,\n \"type\": \"object\"\n },\n \"TextContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\":\ + \ [\n {\n \"const\": \"text\",\n \"\ + type\": \"string\"\n },\n {\n \"type\"\ + : \"null\"\n }\n ],\n \"default\": null,\n\ + \ \"description\": \"The type of the message, in this case `text`.\"\ + ,\n \"title\": \"Type\"\n },\n \"author\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"format\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/TextFormat\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The format of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"content\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The contents of the text message.\",\n \"title\": \"Content\"\ + \n },\n \"attachments\": {\n \"anyOf\": [\n \ + \ {\n \"items\": {\n \"$ref\": \"#/$defs/FileAttachmentEntity\"\ + \n },\n \"type\": \"array\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Optional\ + \ list of file attachments with structured metadata.\",\n \"title\"\ + : \"Attachments\"\n }\n },\n \"title\": \"TextContentEntityOptional\"\ + ,\n \"type\": \"object\"\n },\n \"TextFormat\": {\n \"enum\"\ + : [\n \"markdown\",\n \"plain\",\n \"code\"\n \ + \ ],\n \"title\": \"TextFormat\",\n \"type\": \"string\"\n \ + \ },\n \"ToolRequestContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"tool_request\",\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `tool_request`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"tool_call_id\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The ID of the tool call that is being requested.\",\n \"title\"\ + : \"Tool Call Id\"\n },\n \"name\": {\n \"anyOf\"\ + : [\n {\n \"type\": \"string\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"The\ + \ name of the tool that is being requested.\",\n \"title\": \"\ + Name\"\n },\n \"arguments\": {\n \"anyOf\": [\n \ + \ {\n \"additionalProperties\": true,\n \ + \ \"type\": \"object\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"default\"\ + : null,\n \"description\": \"The arguments to the tool.\",\n \ + \ \"title\": \"Arguments\"\n }\n },\n \"title\"\ + : \"ToolRequestContentEntityOptional\",\n \"type\": \"object\"\n \ + \ },\n \"ToolResponseContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"tool_response\",\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `tool_response`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \"\ + anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"tool_call_id\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The ID of the tool call that is being responded to.\",\n \"\ + title\": \"Tool Call Id\"\n },\n \"name\": {\n \"\ + anyOf\": [\n {\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n }\n\ + \ ],\n \"default\": null,\n \"description\":\ + \ \"The name of the tool that is being responded to.\",\n \"title\"\ + : \"Name\"\n },\n \"content\": {\n \"anyOf\": [\n\ + \ {},\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The result of the tool.\",\n \"title\": \"Content\"\n \ + \ }\n },\n \"title\": \"ToolResponseContentEntityOptional\"\ + ,\n \"type\": \"object\"\n }\n },\n \"description\": \"Filter\ + \ model for TaskMessage - all fields optional for flexible filtering.\\\ + n\\nThe `exclude` field determines whether this filter is inclusionary or\ + \ exclusionary.\\nWhen multiple filters are provided:\\n- Inclusionary filters\ + \ (exclude=False) are OR'd together\\n- Exclusionary filters (exclude=True)\ + \ are OR'd together and negated with $nor\\n- The two groups are AND'd:\ + \ (include1 OR include2) AND NOT (exclude1 OR exclude2)\",\n \"properties\"\ + : {\n \"content\": {\n \"anyOf\": [\n {\n \"$ref\"\ + : \"#/$defs/ToolRequestContentEntityOptional\"\n },\n {\n\ + \ \"$ref\": \"#/$defs/DataContentEntityOptional\"\n },\n\ + \ {\n \"$ref\": \"#/$defs/TextContentEntityOptional\"\n\ + \ },\n {\n \"$ref\": \"#/$defs/ToolResponseContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ReasoningContentEntityOptional\"\ + \n },\n {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Filter by message\ + \ content\",\n \"title\": \"Content\"\n },\n \"streaming_status\"\ + : {\n \"anyOf\": [\n {\n \"enum\": [\n \"\ + IN_PROGRESS\",\n \"DONE\"\n ],\n \"type\":\ + \ \"string\"\n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\": \"Filter\ + \ by streaming status\",\n \"title\": \"Streaming Status\"\n },\n\ + \ \"exclude\": {\n \"default\": false,\n \"description\": \"\ + If true, this filter excludes matching messages\",\n \"title\": \"\ + Exclude\",\n \"type\": \"boolean\"\n }\n },\n \"title\": \"TaskMessageEntityFilter\"\ + ,\n \"type\": \"object\"\n}\n\nEach filter can include:\n- `content`: Filter\ + \ by message content (type, author, data fields)\n- `streaming_status`:\ + \ Filter by status (\"IN_PROGRESS\" or \"DONE\")\n- `exclude`: If true,\ + \ excludes matching messages (default: false)\n\nMultiple filters are combined:\ + \ inclusionary filters (exclude=false) are OR'd together,\nexclusionary\ + \ filters (exclude=true) are OR'd and negated, then both groups are AND'd.\n" + examples: + single_filter: + summary: Filter by content type + value: '{"content": {"type": "text"}}' + multiple_types: + summary: Filter multiple content types (OR) + value: '[{"content": {"type": "text"}}, {"content": {"type": "data"}}]' + with_exclusion: + summary: Include data messages, exclude specific data types + value: '[{"content": {"type": "data"}}, {"content": {"data": {"type": + "error_report"}}, "exclude": true}]' + nested_data: + summary: Filter by nested data field + value: '{"content": {"data": {"type": "report_status_update"}}}' + - name: task_id + in: query + required: true + schema: + type: string + description: The task ID + title: Task Id + description: The task ID + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/TaskMessage' + title: Response List Messages Messages Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /messages/{message_id}: + put: + tags: + - Messages + summary: Update Message + operationId: update_message_messages__message_id__put + parameters: + - name: message_id + in: path + required: true + schema: + type: string + title: Message Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateTaskMessageRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TaskMessage' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Messages + summary: Get Message + operationId: get_message_messages__message_id__get + parameters: + - name: message_id + in: path + required: true + schema: + type: string + title: Message Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/TaskMessage' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /messages/paginated: + get: + tags: + - Messages + summary: List Messages Paginated + description: "List messages for a task with cursor-based pagination.\n\nThis\ + \ endpoint is designed for infinite scroll UIs where new messages may arrive\n\ + while paginating through older ones.\n\nArgs:\n task_id: The task ID to\ + \ filter messages by\n limit: Maximum number of messages to return (default:\ + \ 50)\n cursor: Opaque cursor string for pagination. Pass the `next_cursor`\ + \ from\n a previous response to get the next page.\n direction:\ + \ Pagination direction - \"older\" to get older messages (default),\n \ + \ \"newer\" to get newer messages.\n\nReturns:\n PaginatedMessagesResponse\ + \ with:\n - data: List of messages (newest first when direction=\"older\"\ + )\n - next_cursor: Cursor for fetching the next page (null if no more pages)\n\ + \ - has_more: Whether there are more messages to fetch\n\nExample:\n \ + \ First request: GET /messages/paginated?task_id=xxx&limit=50\n Next page:\ + \ GET /messages/paginated?task_id=xxx&limit=50&cursor=" + operationId: list_messages_paginated_messages_paginated_get + parameters: + - name: limit + in: query + required: false + schema: + type: integer + default: 50 + title: Limit + - name: cursor + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Cursor + - name: direction + in: query + required: false + schema: + enum: + - older + - newer + type: string + default: older + title: Direction + - name: filters + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: "JSON-encoded array of TaskMessageEntityFilter objects.\n\n\ + Schema: {\n \"$defs\": {\n \"DataContentEntityOptional\": {\n \ + \ \"properties\": {\n \"type\": {\n \"anyOf\": [\n \ + \ {\n \"const\": \"data\",\n \"type\"\ + : \"string\"\n },\n {\n \"type\": \"\ + null\"\n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The type of the message, in this case `data`.\"\ + ,\n \"title\": \"Type\"\n },\n \"author\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"data\"\ + : {\n \"anyOf\": [\n {\n \"additionalProperties\"\ + : true,\n \"type\": \"object\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The contents\ + \ of the data message.\",\n \"title\": \"Data\"\n }\n\ + \ },\n \"title\": \"DataContentEntityOptional\",\n \"type\"\ + : \"object\"\n },\n \"FileAttachmentEntity\": {\n \"description\"\ + : \"Represents a file attachment in messages.\",\n \"properties\"\ + : {\n \"file_id\": {\n \"description\": \"The unique ID\ + \ of the attached file\",\n \"title\": \"File Id\",\n \ + \ \"type\": \"string\"\n },\n \"name\": {\n \"\ + description\": \"The name of the file\",\n \"title\": \"Name\"\ + ,\n \"type\": \"string\"\n },\n \"size\": {\n \ + \ \"description\": \"The size of the file in bytes\",\n \ + \ \"title\": \"Size\",\n \"type\": \"integer\"\n },\n\ + \ \"type\": {\n \"description\": \"The MIME type or content\ + \ type of the file\",\n \"title\": \"Type\",\n \"type\"\ + : \"string\"\n }\n },\n \"required\": [\n \"file_id\"\ + ,\n \"name\",\n \"size\",\n \"type\"\n ],\n\ + \ \"title\": \"FileAttachmentEntity\",\n \"type\": \"object\"\ + \n },\n \"MessageAuthor\": {\n \"enum\": [\n \"user\"\ + ,\n \"agent\"\n ],\n \"title\": \"MessageAuthor\",\n\ + \ \"type\": \"string\"\n },\n \"MessageStyle\": {\n \"\ + enum\": [\n \"static\",\n \"active\"\n ],\n \"\ + title\": \"MessageStyle\",\n \"type\": \"string\"\n },\n \"\ + ReasoningContentEntityOptional\": {\n \"properties\": {\n \ + \ \"type\": {\n \"anyOf\": [\n {\n \"\ + const\": \"reasoning\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `reasoning`.\",\n \"\ + title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"summary\"\ + : {\n \"anyOf\": [\n {\n \"items\": {\n\ + \ \"type\": \"string\"\n },\n \ + \ \"type\": \"array\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"A list of short reasoning summaries\"\ + ,\n \"title\": \"Summary\"\n },\n \"content\":\ + \ {\n \"anyOf\": [\n {\n \"items\": {\n\ + \ \"type\": \"string\"\n },\n \ + \ \"type\": \"array\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"The reasoning content or chain-of-thought\ + \ text\",\n \"title\": \"Content\"\n }\n },\n \ + \ \"title\": \"ReasoningContentEntityOptional\",\n \"type\": \"\ + object\"\n },\n \"TextContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"text\",\n \"type\": \"string\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The type of the message, in this case `text`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The role of the messages author, in this case `system`,\ + \ `user`, `assistant`, or `tool`.\"\n },\n \"style\": {\n\ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"format\"\ + : {\n \"anyOf\": [\n {\n \"$ref\": \"\ + #/$defs/TextFormat\"\n },\n {\n \"\ + type\": \"null\"\n }\n ],\n \"default\":\ + \ null,\n \"description\": \"The format of the message. This\ + \ is used by the client to determine how to display the message.\"\n \ + \ },\n \"content\": {\n \"anyOf\": [\n \ + \ {\n \"type\": \"string\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The contents\ + \ of the text message.\",\n \"title\": \"Content\"\n },\n\ + \ \"attachments\": {\n \"anyOf\": [\n {\n \ + \ \"items\": {\n \"$ref\": \"#/$defs/FileAttachmentEntity\"\ + \n },\n \"type\": \"array\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + Optional list of file attachments with structured metadata.\",\n \ + \ \"title\": \"Attachments\"\n }\n },\n \"title\"\ + : \"TextContentEntityOptional\",\n \"type\": \"object\"\n },\n\ + \ \"TextFormat\": {\n \"enum\": [\n \"markdown\",\n \ + \ \"plain\",\n \"code\"\n ],\n \"title\": \"TextFormat\"\ + ,\n \"type\": \"string\"\n },\n \"ToolRequestContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\"\ + : [\n {\n \"const\": \"tool_request\",\n \ + \ \"type\": \"string\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The type of the message,\ + \ in this case `tool_request`.\",\n \"title\": \"Type\"\n \ + \ },\n \"author\": {\n \"anyOf\": [\n {\n\ + \ \"$ref\": \"#/$defs/MessageAuthor\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"tool_call_id\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The ID of the tool call that is being requested.\"\ + ,\n \"title\": \"Tool Call Id\"\n },\n \"name\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The name of the tool that is being requested.\"\ + ,\n \"title\": \"Name\"\n },\n \"arguments\": {\n\ + \ \"anyOf\": [\n {\n \"additionalProperties\"\ + : true,\n \"type\": \"object\"\n },\n \ + \ {\n \"type\": \"null\"\n }\n ],\n\ + \ \"default\": null,\n \"description\": \"The arguments\ + \ to the tool.\",\n \"title\": \"Arguments\"\n }\n \ + \ },\n \"title\": \"ToolRequestContentEntityOptional\",\n \ + \ \"type\": \"object\"\n },\n \"ToolResponseContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\"\ + : [\n {\n \"const\": \"tool_response\",\n \ + \ \"type\": \"string\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The type of the message,\ + \ in this case `tool_response`.\",\n \"title\": \"Type\"\n \ + \ },\n \"author\": {\n \"anyOf\": [\n \ + \ {\n \"$ref\": \"#/$defs/MessageAuthor\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"\ + The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageStyle\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"\ + description\": \"The style of the message. This is used by the client\ + \ to determine how to display the message.\"\n },\n \"tool_call_id\"\ + : {\n \"anyOf\": [\n {\n \"type\": \"\ + string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The ID of the tool call that is being responded\ + \ to.\",\n \"title\": \"Tool Call Id\"\n },\n \"\ + name\": {\n \"anyOf\": [\n {\n \"type\"\ + : \"string\"\n },\n {\n \"type\": \"\ + null\"\n }\n ],\n \"default\": null,\n \ + \ \"description\": \"The name of the tool that is being responded\ + \ to.\",\n \"title\": \"Name\"\n },\n \"content\"\ + : {\n \"anyOf\": [\n {},\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"default\"\ + : null,\n \"description\": \"The result of the tool.\",\n \ + \ \"title\": \"Content\"\n }\n },\n \"title\":\ + \ \"ToolResponseContentEntityOptional\",\n \"type\": \"object\"\n\ + \ }\n },\n \"description\": \"Filter model for TaskMessage - all\ + \ fields optional for flexible filtering.\\n\\nThe `exclude` field determines\ + \ whether this filter is inclusionary or exclusionary.\\nWhen multiple\ + \ filters are provided:\\n- Inclusionary filters (exclude=False) are OR'd\ + \ together\\n- Exclusionary filters (exclude=True) are OR'd together and\ + \ negated with $nor\\n- The two groups are AND'd: (include1 OR include2)\ + \ AND NOT (exclude1 OR exclude2)\",\n \"properties\": {\n \"content\"\ + : {\n \"anyOf\": [\n {\n \"$ref\": \"#/$defs/ToolRequestContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/DataContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/TextContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ToolResponseContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ReasoningContentEntityOptional\"\ + \n },\n {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Filter by message\ + \ content\",\n \"title\": \"Content\"\n },\n \"streaming_status\"\ + : {\n \"anyOf\": [\n {\n \"enum\": [\n \ + \ \"IN_PROGRESS\",\n \"DONE\"\n ],\n \"\ + type\": \"string\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \"description\"\ + : \"Filter by streaming status\",\n \"title\": \"Streaming Status\"\ + \n },\n \"exclude\": {\n \"default\": false,\n \"description\"\ + : \"If true, this filter excludes matching messages\",\n \"title\"\ + : \"Exclude\",\n \"type\": \"boolean\"\n }\n },\n \"title\"\ + : \"TaskMessageEntityFilter\",\n \"type\": \"object\"\n}\n\nEach filter\ + \ can include:\n- `content`: Filter by message content (type, author,\ + \ data fields)\n- `streaming_status`: Filter by status (\"IN_PROGRESS\"\ + \ or \"DONE\")\n- `exclude`: If true, excludes matching messages (default:\ + \ false)\n\nMultiple filters are combined: inclusionary filters (exclude=false)\ + \ are OR'd together,\nexclusionary filters (exclude=true) are OR'd and\ + \ negated, then both groups are AND'd.\n" + title: Filters + description: "JSON-encoded array of TaskMessageEntityFilter objects.\n\nSchema:\ + \ {\n \"$defs\": {\n \"DataContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"data\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `data`.\",\n \"title\"\ + : \"Type\"\n },\n \"author\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageAuthor\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"data\": {\n \ + \ \"anyOf\": [\n {\n \"additionalProperties\": true,\n\ + \ \"type\": \"object\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"\ + default\": null,\n \"description\": \"The contents of the data\ + \ message.\",\n \"title\": \"Data\"\n }\n },\n \ + \ \"title\": \"DataContentEntityOptional\",\n \"type\": \"object\"\ + \n },\n \"FileAttachmentEntity\": {\n \"description\": \"Represents\ + \ a file attachment in messages.\",\n \"properties\": {\n \"\ + file_id\": {\n \"description\": \"The unique ID of the attached\ + \ file\",\n \"title\": \"File Id\",\n \"type\": \"string\"\ + \n },\n \"name\": {\n \"description\": \"The name\ + \ of the file\",\n \"title\": \"Name\",\n \"type\": \"\ + string\"\n },\n \"size\": {\n \"description\": \"\ + The size of the file in bytes\",\n \"title\": \"Size\",\n \ + \ \"type\": \"integer\"\n },\n \"type\": {\n \ + \ \"description\": \"The MIME type or content type of the file\",\n \ + \ \"title\": \"Type\",\n \"type\": \"string\"\n }\n\ + \ },\n \"required\": [\n \"file_id\",\n \"name\"\ + ,\n \"size\",\n \"type\"\n ],\n \"title\": \"FileAttachmentEntity\"\ + ,\n \"type\": \"object\"\n },\n \"MessageAuthor\": {\n \"\ + enum\": [\n \"user\",\n \"agent\"\n ],\n \"title\"\ + : \"MessageAuthor\",\n \"type\": \"string\"\n },\n \"MessageStyle\"\ + : {\n \"enum\": [\n \"static\",\n \"active\"\n ],\n\ + \ \"title\": \"MessageStyle\",\n \"type\": \"string\"\n },\n\ + \ \"ReasoningContentEntityOptional\": {\n \"properties\": {\n \ + \ \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"reasoning\",\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `reasoning`.\",\n \"\ + title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"summary\": {\n \ + \ \"anyOf\": [\n {\n \"items\": {\n \ + \ \"type\": \"string\"\n },\n \"type\":\ + \ \"array\"\n },\n {\n \"type\": \"null\"\ + \n }\n ],\n \"default\": null,\n \"\ + description\": \"A list of short reasoning summaries\",\n \"title\"\ + : \"Summary\"\n },\n \"content\": {\n \"anyOf\":\ + \ [\n {\n \"items\": {\n \"type\"\ + : \"string\"\n },\n \"type\": \"array\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The reasoning content or chain-of-thought text\",\n \"title\"\ + : \"Content\"\n }\n },\n \"title\": \"ReasoningContentEntityOptional\"\ + ,\n \"type\": \"object\"\n },\n \"TextContentEntityOptional\"\ + : {\n \"properties\": {\n \"type\": {\n \"anyOf\":\ + \ [\n {\n \"const\": \"text\",\n \"\ + type\": \"string\"\n },\n {\n \"type\"\ + : \"null\"\n }\n ],\n \"default\": null,\n\ + \ \"description\": \"The type of the message, in this case `text`.\"\ + ,\n \"title\": \"Type\"\n },\n \"author\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"format\": {\n \ + \ \"anyOf\": [\n {\n \"$ref\": \"#/$defs/TextFormat\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The format of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"content\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The contents of the text message.\",\n \"title\": \"Content\"\ + \n },\n \"attachments\": {\n \"anyOf\": [\n \ + \ {\n \"items\": {\n \"$ref\": \"#/$defs/FileAttachmentEntity\"\ + \n },\n \"type\": \"array\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Optional\ + \ list of file attachments with structured metadata.\",\n \"title\"\ + : \"Attachments\"\n }\n },\n \"title\": \"TextContentEntityOptional\"\ + ,\n \"type\": \"object\"\n },\n \"TextFormat\": {\n \"enum\"\ + : [\n \"markdown\",\n \"plain\",\n \"code\"\n \ + \ ],\n \"title\": \"TextFormat\",\n \"type\": \"string\"\n \ + \ },\n \"ToolRequestContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"tool_request\",\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `tool_request`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \"anyOf\"\ + : [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\n\ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"tool_call_id\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The ID of the tool call that is being requested.\",\n \"title\"\ + : \"Tool Call Id\"\n },\n \"name\": {\n \"anyOf\"\ + : [\n {\n \"type\": \"string\"\n },\n\ + \ {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"The\ + \ name of the tool that is being requested.\",\n \"title\": \"\ + Name\"\n },\n \"arguments\": {\n \"anyOf\": [\n \ + \ {\n \"additionalProperties\": true,\n \ + \ \"type\": \"object\"\n },\n {\n \ + \ \"type\": \"null\"\n }\n ],\n \"default\"\ + : null,\n \"description\": \"The arguments to the tool.\",\n \ + \ \"title\": \"Arguments\"\n }\n },\n \"title\"\ + : \"ToolRequestContentEntityOptional\",\n \"type\": \"object\"\n \ + \ },\n \"ToolResponseContentEntityOptional\": {\n \"properties\"\ + : {\n \"type\": {\n \"anyOf\": [\n {\n \ + \ \"const\": \"tool_response\",\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The type of the message, in this case `tool_response`.\",\n \ + \ \"title\": \"Type\"\n },\n \"author\": {\n \"\ + anyOf\": [\n {\n \"$ref\": \"#/$defs/MessageAuthor\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The role of the messages author, in this case `system`, `user`, `assistant`,\ + \ or `tool`.\"\n },\n \"style\": {\n \"anyOf\": [\n\ + \ {\n \"$ref\": \"#/$defs/MessageStyle\"\n \ + \ },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The style of the message. This is used by the client to determine how\ + \ to display the message.\"\n },\n \"tool_call_id\": {\n \ + \ \"anyOf\": [\n {\n \"type\": \"string\"\ + \n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The ID of the tool call that is being responded to.\",\n \"\ + title\": \"Tool Call Id\"\n },\n \"name\": {\n \"\ + anyOf\": [\n {\n \"type\": \"string\"\n \ + \ },\n {\n \"type\": \"null\"\n }\n\ + \ ],\n \"default\": null,\n \"description\":\ + \ \"The name of the tool that is being responded to.\",\n \"title\"\ + : \"Name\"\n },\n \"content\": {\n \"anyOf\": [\n\ + \ {},\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\"\ + : \"The result of the tool.\",\n \"title\": \"Content\"\n \ + \ }\n },\n \"title\": \"ToolResponseContentEntityOptional\"\ + ,\n \"type\": \"object\"\n }\n },\n \"description\": \"Filter\ + \ model for TaskMessage - all fields optional for flexible filtering.\\\ + n\\nThe `exclude` field determines whether this filter is inclusionary or\ + \ exclusionary.\\nWhen multiple filters are provided:\\n- Inclusionary filters\ + \ (exclude=False) are OR'd together\\n- Exclusionary filters (exclude=True)\ + \ are OR'd together and negated with $nor\\n- The two groups are AND'd:\ + \ (include1 OR include2) AND NOT (exclude1 OR exclude2)\",\n \"properties\"\ + : {\n \"content\": {\n \"anyOf\": [\n {\n \"$ref\"\ + : \"#/$defs/ToolRequestContentEntityOptional\"\n },\n {\n\ + \ \"$ref\": \"#/$defs/DataContentEntityOptional\"\n },\n\ + \ {\n \"$ref\": \"#/$defs/TextContentEntityOptional\"\n\ + \ },\n {\n \"$ref\": \"#/$defs/ToolResponseContentEntityOptional\"\ + \n },\n {\n \"$ref\": \"#/$defs/ReasoningContentEntityOptional\"\ + \n },\n {\n \"type\": \"null\"\n }\n \ + \ ],\n \"default\": null,\n \"description\": \"Filter by message\ + \ content\",\n \"title\": \"Content\"\n },\n \"streaming_status\"\ + : {\n \"anyOf\": [\n {\n \"enum\": [\n \"\ + IN_PROGRESS\",\n \"DONE\"\n ],\n \"type\":\ + \ \"string\"\n },\n {\n \"type\": \"null\"\n \ + \ }\n ],\n \"default\": null,\n \"description\": \"Filter\ + \ by streaming status\",\n \"title\": \"Streaming Status\"\n },\n\ + \ \"exclude\": {\n \"default\": false,\n \"description\": \"\ + If true, this filter excludes matching messages\",\n \"title\": \"\ + Exclude\",\n \"type\": \"boolean\"\n }\n },\n \"title\": \"TaskMessageEntityFilter\"\ + ,\n \"type\": \"object\"\n}\n\nEach filter can include:\n- `content`: Filter\ + \ by message content (type, author, data fields)\n- `streaming_status`:\ + \ Filter by status (\"IN_PROGRESS\" or \"DONE\")\n- `exclude`: If true,\ + \ excludes matching messages (default: false)\n\nMultiple filters are combined:\ + \ inclusionary filters (exclude=false) are OR'd together,\nexclusionary\ + \ filters (exclude=true) are OR'd and negated, then both groups are AND'd.\n" + examples: + single_filter: + summary: Filter by content type + value: '{"content": {"type": "text"}}' + multiple_types: + summary: Filter multiple content types (OR) + value: '[{"content": {"type": "text"}}, {"content": {"type": "data"}}]' + with_exclusion: + summary: Include data messages, exclude specific data types + value: '[{"content": {"type": "data"}}, {"content": {"data": {"type": + "error_report"}}, "exclude": true}]' + nested_data: + summary: Filter by nested data field + value: '{"content": {"data": {"type": "report_status_update"}}}' + - name: task_id + in: query + required: true + schema: + type: string + description: The task ID + title: Task Id + description: The task ID + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/PaginatedMessagesResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /spans: + post: + tags: + - Spans + summary: Create Span + description: Create a new span with the provided parameters + operationId: create_span_spans_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateSpanRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Span' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Spans + summary: List Spans + description: List spans, optionally filtered by trace_id and/or task_id + operationId: list_spans_spans_get + parameters: + - name: trace_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Trace Id + - name: task_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Task Id + - name: limit + in: query + required: false + schema: + type: integer + maximum: 1000 + minimum: 1 + default: 50 + title: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + default: 1 + title: Page Number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Order By + - name: order_direction + in: query + required: false + schema: + type: string + default: desc + title: Order Direction + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Span' + title: Response List Spans Spans Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /spans/{span_id}: + patch: + tags: + - Spans + summary: Partial Update Span + description: Update a span with the provided output data and mark it as complete + operationId: partial_update_span_spans__span_id__patch + parameters: + - name: span_id + in: path + required: true + schema: + type: string + title: Span Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateSpanRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Span' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Spans + summary: Get Span + description: Get a span by ID + operationId: get_span_spans__span_id__get + parameters: + - name: span_id + in: path + required: true + schema: + type: string + title: Span Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Span' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /states: + post: + tags: + - States + summary: Create Task State + operationId: create_task_state_states_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateStateRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/State' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - States + summary: List States + description: List all states, optionally filtered by query parameters. + operationId: filter_states_states_get + parameters: + - name: task_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Task ID + title: Task Id + description: Task ID + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Agent ID + title: Agent Id + description: Agent ID + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + description: Limit + default: 50 + title: Limit + description: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + description: Page number + default: 1 + title: Page Number + description: Page number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Field to order by + title: Order By + description: Field to order by + - name: order_direction + in: query + required: false + schema: + type: string + description: Order direction (asc or desc) + default: desc + title: Order Direction + description: Order direction (asc or desc) + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/State' + title: Response Filter States States Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /states/{state_id}: + get: + tags: + - States + summary: Get State by State ID + description: Get a state by its unique state ID. + operationId: get_state_states__state_id__get + parameters: + - name: state_id + in: path + required: true + schema: + type: string + title: State Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/State' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + tags: + - States + summary: Update Task State + operationId: update_task_state_states__state_id__put + parameters: + - name: state_id + in: path + required: true + schema: + type: string + title: State Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateStateRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/State' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - States + summary: Delete Task State + operationId: delete_task_state_states__state_id__delete + parameters: + - name: state_id + in: path + required: true + schema: + type: string + title: State Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/State' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /events/{event_id}: + get: + tags: + - Events + summary: Get Event + operationId: get_event_events__event_id__get + parameters: + - name: event_id + in: path + required: true + schema: + type: string + title: Event Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Event' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /events: + get: + tags: + - Events + summary: List Events + description: 'List events for a specific task and agent. + + + Optionally filter for events after a specific sequence ID. + + Results are ordered by sequence_id.' + operationId: list_events_events_get + parameters: + - name: last_processed_event_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Optional event ID to get events after this ID + title: Last Processed Event Id + description: Optional event ID to get events after this ID + - name: limit + in: query + required: false + schema: + anyOf: + - type: integer + maximum: 1000 + minimum: 1 + - type: 'null' + description: Optional limit on number of results + title: Limit + description: Optional limit on number of results + - name: task_id + in: query + required: true + schema: + type: string + description: The task ID to filter events by + title: Task Id + description: The task ID to filter events by + - name: agent_id + in: query + required: true + schema: + type: string + description: The agent ID to filter events by + title: Agent Id + description: The agent ID to filter events by + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Event' + title: Response List Events Events Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tracker/{tracker_id}: + get: + tags: + - Agent Task Tracker + summary: Get Agent Task Tracker + description: Get agent task tracker by tracker ID + operationId: get_agent_task_tracker_tracker__tracker_id__get + parameters: + - name: tracker_id + in: path + required: true + schema: + type: string + title: Tracker Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentTaskTracker' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + put: + tags: + - Agent Task Tracker + summary: Update Agent Task Tracker + description: Update agent task tracker by tracker ID + operationId: update_agent_task_tracker_tracker__tracker_id__put + parameters: + - name: tracker_id + in: path + required: true + schema: + type: string + title: Tracker Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/UpdateAgentTaskTrackerRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentTaskTracker' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tracker: + get: + tags: + - Agent Task Tracker + summary: List Agent Task Trackers + description: List all agent task trackers, optionally filtered by query parameters. + operationId: filter_agent_task_tracker_tracker_get + parameters: + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Agent ID + title: Agent Id + description: Agent ID + - name: task_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Task ID + title: Task Id + description: Task ID + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + description: Limit + default: 50 + title: Limit + description: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + description: Page number + default: 1 + title: Page Number + description: Page number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Field to order by + title: Order By + description: Field to order by + - name: order_direction + in: query + required: false + schema: + type: string + description: Order direction (asc or desc) + default: desc + title: Order Direction + description: Order direction (asc or desc) + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AgentTaskTracker' + title: Response Filter Agent Task Tracker Tracker Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agent_api_keys: + post: + tags: + - Agent APIKeys + summary: Create Api Key + operationId: create_api_key_agent_api_keys_post + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAPIKeyRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/CreateAPIKeyResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Agent APIKeys + summary: List API keys for an agent ID + description: List API keys for an agent ID. + operationId: list_agent_api_keys_agent_api_keys_get + parameters: + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: agent_name + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Name + - name: limit + in: query + required: false + schema: + type: integer + maximum: 1000 + minimum: 1 + default: 50 + title: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + default: 1 + title: Page Number + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/AgentAPIKey' + title: Response List Agent Api Keys Agent Api Keys Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agent_api_keys/name/{name}: + get: + tags: + - Agent APIKeys + summary: Return named API key for the agent ID + description: Return named API key for the agent ID. + operationId: get_agent_api_key_by_name_agent_api_keys_name__name__get + parameters: + - name: name + in: path + required: true + schema: + type: string + title: Name + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: agent_name + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Name + - name: api_key_type + in: query + required: false + schema: + $ref: '#/components/schemas/AgentAPIKeyType' + default: external + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentAPIKey' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agent_api_keys/{id}: + get: + tags: + - Agent APIKeys + summary: Return the API key by ID + description: Return API key by ID. + operationId: get_agent_api_key_agent_api_keys__id__get + parameters: + - name: id + in: path + required: true + schema: + type: string + title: Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentAPIKey' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Agent APIKeys + summary: Delete API key by ID + description: Delete API key by ID. + operationId: delete_agent_api_key_agent_api_keys__id__delete + parameters: + - name: id + in: path + required: true + schema: + type: string + title: Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: string + title: Response Delete Agent Api Key Agent Api Keys Id Delete + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agent_api_keys/name/{api_key_name}: + delete: + tags: + - Agent APIKeys + summary: Delete API key by name + description: Delete API key by name. + operationId: delete_agent_api_key_by_name_agent_api_keys_name__api_key_name__delete + parameters: + - name: api_key_name + in: path + required: true + schema: + type: string + title: Api Key Name + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: agent_name + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Name + - name: api_key_type + in: query + required: false + schema: + $ref: '#/components/schemas/AgentAPIKeyType' + default: external + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: string + title: Response Delete Agent Api Key By Name Agent Api Keys Name Api + Key Name Delete + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /deployment-history/{deployment_id}: + get: + tags: + - Deployment History + summary: Get Deployment by ID + description: Get a deployment record by its unique ID. + operationId: get_deployment_by_id_deployment_history__deployment_id__get + parameters: + - name: deployment_id + in: path + required: true + schema: + type: string + title: Deployment Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeploymentHistory' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /deployment-history: + get: + tags: + - Deployment History + summary: List Deployments for an agent + description: List deployment history for an agent. + operationId: list_deployments_deployment_history_get + parameters: + - name: agent_id + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Id + - name: agent_name + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Agent Name + - name: limit + in: query + required: false + schema: + type: integer + default: 50 + title: Limit + - name: page_number + in: query + required: false + schema: + type: integer + default: 1 + title: Page Number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + title: Order By + - name: order_direction + in: query + required: false + schema: + type: string + default: desc + title: Order Direction + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/DeploymentHistory' + title: Response List Deployments Deployment History Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/deployments: + post: + tags: + - Deployments + summary: Create Deployment + description: Create a new deployment record in PENDING status. + operationId: create_deployment_agents__agent_id__deployments_post + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateDeploymentRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Deployments + summary: List Deployments + description: List deployments for an agent, newest first. + operationId: list_deployments_agents__agent_id__deployments_get + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: limit + in: query + required: false + schema: + type: integer + minimum: 1 + description: Limit + default: 50 + title: Limit + description: Limit + - name: page_number + in: query + required: false + schema: + type: integer + minimum: 1 + description: Page number + default: 1 + title: Page Number + description: Page number + - name: order_by + in: query + required: false + schema: + anyOf: + - type: string + - type: 'null' + description: Field to order by + title: Order By + description: Field to order by + - name: order_direction + in: query + required: false + schema: + type: string + description: Order direction (asc or desc) + default: desc + title: Order Direction + description: Order direction (asc or desc) + responses: + '200': + description: Successful Response + content: + application/json: + schema: + type: array + items: + $ref: '#/components/schemas/Deployment' + title: Response List Deployments Agents Agent Id Deployments Get + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/deployments/{deployment_id}: + get: + tags: + - Deployments + summary: Get Deployment + description: Get a specific deployment by ID. + operationId: get_deployment_agents__agent_id__deployments__deployment_id__get + parameters: + - name: deployment_id + in: path + required: true + schema: + type: string + title: Deployment Id + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Deployments + summary: Delete Deployment + description: Delete a non-production deployment. + operationId: delete_deployment_agents__agent_id__deployments__deployment_id__delete + parameters: + - name: deployment_id + in: path + required: true + schema: + type: string + title: Deployment Id + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/deployments/{deployment_id}/promote: + post: + tags: + - Deployments + summary: Promote Deployment + description: Promote a deployment to production with atomic cutover. + operationId: promote_deployment_agents__agent_id__deployments__deployment_id__promote_post + parameters: + - name: deployment_id + in: path + required: true + schema: + type: string + title: Deployment Id + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/Deployment' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/deployments/{deployment_id}/rpc: + post: + tags: + - Deployments + summary: Preview RPC + description: Send an RPC request to a specific deployment (for preview testing). + operationId: handle_deployment_rpc_agents__agent_id__deployments__deployment_id__rpc_post + parameters: + - name: deployment_id + in: path + required: true + schema: + type: string + title: Deployment Id + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/AgentRPCResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/schedules: + post: + tags: + - Schedules + summary: Create Schedule + description: Create a new schedule for recurring workflow execution for an agent. + operationId: create_schedule_agents__agent_id__schedules_post + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CreateScheduleRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + get: + tags: + - Schedules + summary: List Agent Schedules + description: List all schedules for an agent. + operationId: list_schedules_agents__agent_id__schedules_get + parameters: + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + - name: page_size + in: query + required: false + schema: + type: integer + maximum: 1000 + minimum: 1 + default: 100 + title: Page Size + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleListResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/schedules/{schedule_name}: + get: + tags: + - Schedules + summary: Get Schedule + description: Get details of a schedule by its name. + operationId: get_schedule_agents__agent_id__schedules__schedule_name__get + parameters: + - name: schedule_name + in: path + required: true + schema: + type: string + title: Schedule Name + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + delete: + tags: + - Schedules + summary: Delete Schedule + description: Delete a schedule permanently. + operationId: delete_schedule_agents__agent_id__schedules__schedule_name__delete + parameters: + - name: schedule_name + in: path + required: true + schema: + type: string + title: Schedule Name + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/schedules/{schedule_name}/pause: + post: + tags: + - Schedules + summary: Pause Schedule + description: Pause a schedule to stop it from executing. + operationId: pause_schedule_agents__agent_id__schedules__schedule_name__pause_post + parameters: + - name: schedule_name + in: path + required: true + schema: + type: string + title: Schedule Name + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/PauseScheduleRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/schedules/{schedule_name}/unpause: + post: + tags: + - Schedules + summary: Unpause Schedule + description: Unpause/resume a schedule to allow it to execute again. + operationId: unpause_schedule_agents__agent_id__schedules__schedule_name__unpause_post + parameters: + - name: schedule_name + in: path + required: true + schema: + type: string + title: Schedule Name + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + requestBody: + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/UnpauseScheduleRequest' + - type: 'null' + title: Request + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /agents/{agent_id}/schedules/{schedule_name}/trigger: + post: + tags: + - Schedules + summary: Trigger Schedule + description: Trigger a schedule to run immediately, regardless of its regular + schedule. + operationId: trigger_schedule_agents__agent_id__schedules__schedule_name__trigger_post + parameters: + - name: schedule_name + in: path + required: true + schema: + type: string + title: Schedule Name + - name: agent_id + in: path + required: true + schema: + type: string + title: Agent Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ScheduleResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /checkpoints/get-tuple: + post: + tags: + - Checkpoints + summary: Get Checkpoint Tuple + operationId: get_checkpoint_tuple_checkpoints_get_tuple_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/GetCheckpointTupleRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + anyOf: + - $ref: '#/components/schemas/CheckpointTupleResponse' + - type: 'null' + title: Response Get Checkpoint Tuple Checkpoints Get Tuple Post + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /checkpoints/put: + post: + tags: + - Checkpoints + summary: Put Checkpoint + operationId: put_checkpoint_checkpoints_put_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PutCheckpointRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/PutCheckpointResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /checkpoints/put-writes: + post: + tags: + - Checkpoints + summary: Put Writes + operationId: put_writes_checkpoints_put_writes_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/PutWritesRequest' + required: true + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /checkpoints/list: + post: + tags: + - Checkpoints + summary: List Checkpoints + operationId: list_checkpoints_checkpoints_list_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/ListCheckpointsRequest' + required: true + responses: + '200': + description: Successful Response + content: + application/json: + schema: + items: + $ref: '#/components/schemas/CheckpointListItem' + type: array + title: Response List Checkpoints Checkpoints List Post + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /checkpoints/delete-thread: + post: + tags: + - Checkpoints + summary: Delete Thread + operationId: delete_thread_checkpoints_delete_thread_post + requestBody: + content: + application/json: + schema: + $ref: '#/components/schemas/DeleteThreadRequest' + required: true + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/export: + get: + tags: + - task-retention + summary: Export Task + description: 'Build a self-contained snapshot of a task''s content surfaces. + + + Returns the exact payload format that POST /rehydrate accepts, so + + export → clean → rehydrate is a round-trip-equivalent operation.' + operationId: export_task_tasks__task_id__export_get + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ExportTaskResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + post: + tags: + - task-retention + summary: Export Task To Url + description: 'Build the task snapshot and PUT it to a caller-supplied presigned + URL. + + + Use this when the snapshot is too large for a JSON response body (long + + conversations, deep reasoning content, many attachments). The upload URL + + must be https and resolve to a public address — see SSRF guard.' + operationId: export_task_to_url_tasks__task_id__export_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/ExportTaskToUrlRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/ExportTaskToUrlResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/clean: + post: + tags: + - task-retention + summary: Clean Task + description: 'Delete content-bearing rows for a stale task. + + + Refuses on active tasks, in-flight workflows, or unprocessed events + + regardless of `force`. The `force=true` flag only bypasses the + + idle-threshold check.' + operationId: clean_task_tasks__task_id__clean_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/CleanTaskRequest' + responses: + '200': + description: Successful Response + content: + application/json: + schema: + $ref: '#/components/schemas/CleanTaskResponse' + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' + /tasks/{task_id}/rehydrate: + post: + tags: + - task-retention + summary: Rehydrate Task + description: 'Restore content-bearing rows from a snapshot. + + + Two modes: + + - Inline: caller provides messages and task_states in the request body. + + - URL: caller provides snapshot_url; Agentex downloads and parses it. + + + Refuses if the task isn''t currently in a cleaned state, or if any supplied + + message/state ID already exists in Mongo (catches double-rehydrate).' + operationId: rehydrate_task_tasks__task_id__rehydrate_post + parameters: + - name: task_id + in: path + required: true + schema: + type: string + title: Task Id + requestBody: + required: true + content: + application/json: + schema: + $ref: '#/components/schemas/RehydrateTaskRequest' + responses: + '204': + description: Successful Response + '422': + description: Validation Error + content: + application/json: + schema: + $ref: '#/components/schemas/HTTPValidationError' +components: + schemas: + ACPType: + type: string + enum: + - sync + - async + - agentic + title: ACPType + Agent: + properties: + id: + type: string + title: Id + description: The unique identifier of the agent. + name: + type: string + title: Name + description: The unique name of the agent. + description: + type: string + title: Description + description: The description of the action. + status: + $ref: '#/components/schemas/AgentStatus' + description: The status of the action, indicating if it's building, ready, + failed, etc. + default: Unknown + acp_type: + $ref: '#/components/schemas/ACPType' + description: The type of the ACP Server (Either sync or async) + status_reason: + anyOf: + - type: string + - type: 'null' + title: Status Reason + description: The reason for the status of the action. + created_at: + type: string + format: date-time + title: Created At + description: The timestamp when the agent was created + updated_at: + type: string + format: date-time + title: Updated At + description: The timestamp when the agent was last updated + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: The metadata for the agent's registration. + registered_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Registered At + description: The timestamp when the agent was last registered + agent_input_type: + anyOf: + - $ref: '#/components/schemas/AgentInputType' + - type: 'null' + description: The type of input the agent expects. + production_deployment_id: + anyOf: + - type: string + - type: 'null' + title: Production Deployment Id + description: ID of the current production deployment. + type: object + required: + - id + - name + - description + - acp_type + - created_at + - updated_at + title: Agent + AgentAPIKey: + properties: + id: + type: string + title: Id + description: The unique identifier of the agent API key. + agent_id: + type: string + title: Agent Id + description: The UUID of the agent + created_at: + type: string + format: date-time + title: Created At + description: When the agent API key was created + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: The optional name of the agent API key. + api_key_type: + $ref: '#/components/schemas/AgentAPIKeyType' + description: The type of the agent API key (either internal or external) + type: object + required: + - id + - agent_id + - created_at + - name + - api_key_type + title: AgentAPIKey + AgentAPIKeyType: + type: string + enum: + - internal + - external + - github + - slack + title: AgentAPIKeyType + AgentInputType: + type: string + enum: + - text + - json + title: AgentInputType + AgentRPCMethod: + type: string + enum: + - event/send + - task/create + - message/send + - task/cancel + title: AgentRPCMethod + AgentRPCParams: + anyOf: + - $ref: '#/components/schemas/CreateTaskRequest' + - $ref: '#/components/schemas/CancelTaskRequest' + - $ref: '#/components/schemas/SendMessageRequest' + - $ref: '#/components/schemas/SendEventRequest' + title: AgentRPCParams + description: The parameters for the agent RPC request + AgentRPCRequest: + properties: + jsonrpc: + type: string + const: '2.0' + title: Jsonrpc + default: '2.0' + method: + $ref: '#/components/schemas/AgentRPCMethod' + params: + $ref: '#/components/schemas/AgentRPCParams' + id: + anyOf: + - type: integer + - type: string + - type: 'null' + title: Id + type: object + required: + - method + - params + title: AgentRPCRequest + AgentRPCResponse: + properties: + jsonrpc: + type: string + const: '2.0' + title: Jsonrpc + default: '2.0' + result: + $ref: '#/components/schemas/AgentRPCResult' + description: The result of the agent RPC request + error: + anyOf: + - {} + - type: 'null' + title: Error + id: + anyOf: + - type: integer + - type: string + - type: 'null' + title: Id + type: object + required: + - result + title: AgentRPCResponse + AgentRPCResult: + anyOf: + - items: + $ref: '#/components/schemas/TaskMessage' + type: array + - $ref: '#/components/schemas/TaskMessageUpdate' + - $ref: '#/components/schemas/Task' + - $ref: '#/components/schemas/Event' + - type: 'null' + title: AgentRPCResult + AgentStatus: + type: string + enum: + - Ready + - Failed + - Unknown + - Deleted + - Unhealthy + - BuildOnly + title: AgentStatus + AgentTaskTracker: + properties: + id: + type: string + title: Id + description: The UUID of the agent task tracker + agent_id: + type: string + title: Agent Id + description: The UUID of the agent + task_id: + type: string + title: Task Id + description: The UUID of the task + status: + anyOf: + - type: string + - type: 'null' + title: Status + description: Processing status + status_reason: + anyOf: + - type: string + - type: 'null' + title: Status Reason + description: Optional status reason + last_processed_event_id: + anyOf: + - type: string + - type: 'null' + title: Last Processed Event Id + description: The last processed event ID + created_at: + type: string + format: date-time + title: Created At + description: When the agent task tracker was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: When the agent task tracker was last updated + type: object + required: + - id + - agent_id + - task_id + - created_at + title: AgentTaskTracker + BatchCreateTaskMessagesRequest: + properties: + task_id: + type: string + title: The unique id of the task to send the messages to + contents: + items: + $ref: '#/components/schemas/TaskMessageContent' + type: array + title: The messages to send to the task. The order of the messages will + be the order they are added to the task. + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Optional caller-supplied base creation timestamp for the batch + description: Optional base timestamp. Each message in the batch is stamped + with base + i milliseconds to guarantee unique, monotonic ordering. If + omitted, the server stamps datetime.now(UTC) at insert time. + type: object + required: + - task_id + - contents + title: BatchCreateTaskMessagesRequest + BatchUpdateTaskMessagesRequest: + properties: + task_id: + type: string + title: The unique id of the task to update the messages of + updates: + additionalProperties: + $ref: '#/components/schemas/TaskMessageContent' + type: object + title: The updates to apply to the messages. The key is the TaskMessage + id and the value is the TaskMessageContent to update the message with. + type: object + required: + - task_id + - updates + title: BatchUpdateTaskMessagesRequest + BlobData: + properties: + channel: + type: string + title: Channel name + version: + type: string + title: Channel version + type: + type: string + title: Serialization type tag + blob: + anyOf: + - type: string + - type: 'null' + title: Base64-encoded binary data + type: object + required: + - channel + - version + - type + title: BlobData + BlobResponse: + properties: + channel: + type: string + title: Channel + version: + type: string + title: Version + type: + type: string + title: Type + blob: + anyOf: + - type: string + - type: 'null' + title: Blob + type: object + required: + - channel + - version + - type + title: BlobResponse + CancelTaskRequest: + properties: + task_id: + anyOf: + - type: string + - type: 'null' + title: Task Id + description: The ID of the task to cancel. Either this or task_name must + be provided. + task_name: + anyOf: + - type: string + - type: 'null' + title: Task Name + description: The name of the task to cancel. Either this or task_id must + be provided. + type: object + title: CancelTaskRequest + CheckpointListItem: + properties: + thread_id: + type: string + title: Thread Id + checkpoint_ns: + type: string + title: Checkpoint Ns + checkpoint_id: + type: string + title: Checkpoint Id + parent_checkpoint_id: + anyOf: + - type: string + - type: 'null' + title: Parent Checkpoint Id + checkpoint: + additionalProperties: true + type: object + title: Checkpoint + metadata: + additionalProperties: true + type: object + title: Metadata + type: object + required: + - thread_id + - checkpoint_ns + - checkpoint_id + - checkpoint + - metadata + title: CheckpointListItem + CheckpointTupleResponse: + properties: + thread_id: + type: string + title: Thread Id + checkpoint_ns: + type: string + title: Checkpoint Ns + checkpoint_id: + type: string + title: Checkpoint Id + parent_checkpoint_id: + anyOf: + - type: string + - type: 'null' + title: Parent Checkpoint Id + checkpoint: + additionalProperties: true + type: object + title: Checkpoint + metadata: + additionalProperties: true + type: object + title: Metadata + blobs: + items: + $ref: '#/components/schemas/BlobResponse' + type: array + title: Blobs + pending_writes: + items: + $ref: '#/components/schemas/WriteResponse' + type: array + title: Pending Writes + type: object + required: + - thread_id + - checkpoint_ns + - checkpoint_id + - checkpoint + - metadata + title: CheckpointTupleResponse + CleanTaskRequest: + properties: + force: + type: boolean + title: Force + description: Skip the idle-threshold check. Active-workflow and unprocessed-events + checks still apply. Admin use only. + default: false + idle_days: + type: integer + minimum: 1.0 + title: Idle Days + description: Idle threshold in days (ignored when force=true). + default: 7 + type: object + title: CleanTaskRequest + CleanTaskResponse: + properties: + task_id: + type: string + title: Task Id + cleaned_at: + type: string + format: date-time + title: Cleaned At + messages_deleted: + type: integer + title: Messages Deleted + task_states_deleted: + type: integer + title: Task States Deleted + events_deleted: + type: integer + title: Events Deleted + type: object + required: + - task_id + - cleaned_at + - messages_deleted + - task_states_deleted + - events_deleted + title: CleanTaskResponse + CreateAPIKeyRequest: + properties: + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + description: The UUID of the agent + agent_name: + anyOf: + - type: string + - type: 'null' + title: Agent Name + description: The name of the agent - if not provided, the agent_id must + be set. + name: + type: string + title: Name + description: The name of the agent's API key. + api_key_type: + $ref: '#/components/schemas/AgentAPIKeyType' + description: The type of the agent API key (external by default). + default: external + api_key: + anyOf: + - type: string + - type: 'null' + title: Api Key + description: Optionally provide the API key value - if not set, one will + be generated. + type: object + required: + - name + title: CreateAPIKeyRequest + CreateAPIKeyResponse: + properties: + id: + type: string + title: Id + description: The unique identifier of the agent API key. + agent_id: + type: string + title: Agent Id + description: The UUID of the agent + created_at: + type: string + format: date-time + title: Created At + description: When the agent API key was created + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: The optional name of the agent API key. + api_key_type: + $ref: '#/components/schemas/AgentAPIKeyType' + description: The type of the created agent API key (external). + api_key: + type: string + title: Api Key + description: The value of the newly created API key. + type: object + required: + - id + - agent_id + - created_at + - name + - api_key_type + - api_key + title: CreateAPIKeyResponse + CreateDeploymentRequest: + properties: + docker_image: + type: string + title: Docker Image + description: Full Docker image URI. + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: Git/build metadata (commit_hash, branch_name, author_name, + author_email, build_timestamp). + sgp_deploy_id: + anyOf: + - type: string + - type: 'null' + title: Sgp Deploy Id + description: SGP deployment ID. + helm_release_name: + anyOf: + - type: string + - type: 'null' + title: Helm Release Name + description: Helm release name. + type: object + required: + - docker_image + title: CreateDeploymentRequest + CreateScheduleRequest: + properties: + name: + type: string + maxLength: 64 + minLength: 1 + pattern: ^[a-z0-9][a-z0-9-]*[a-z0-9]$|^[a-z0-9]$ + title: Schedule Name + description: Human-readable name for the schedule (e.g., 'weekly-profiling'). + Will be combined with agent_id to form the full schedule_id. + workflow_name: + type: string + title: Workflow Name + description: Name of the Temporal workflow to execute (e.g., 'sae-orchestrator') + task_queue: + type: string + title: Task Queue + description: Temporal task queue where the agent's worker is listening + workflow_params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Workflow Parameters + description: Parameters to pass to the workflow + cron_expression: + anyOf: + - type: string + - type: 'null' + title: Cron Expression + description: Cron expression for scheduling (e.g., '0 0 * * 0' for weekly + on Sunday) + interval_seconds: + anyOf: + - type: integer + minimum: 1.0 + - type: 'null' + title: Interval Seconds + description: Alternative to cron - run every N seconds + execution_timeout_seconds: + anyOf: + - type: integer + minimum: 1.0 + - type: 'null' + title: Execution Timeout + description: Maximum time in seconds for each workflow execution + start_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Start At + description: When the schedule should start being active + end_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: End At + description: When the schedule should stop being active + paused: + type: boolean + title: Paused + description: Whether to create the schedule in a paused state + default: false + type: object + required: + - name + - workflow_name + - task_queue + title: CreateScheduleRequest + description: Request model for creating a new schedule for an agent + CreateSpanRequest: + properties: + id: + anyOf: + - type: string + - type: 'null' + title: Unique Span ID + description: Unique identifier for the span. If not provided, an ID will + be generated. + trace_id: + type: string + title: The trace ID for this span + description: Unique identifier for the trace this span belongs to + task_id: + anyOf: + - type: string + - type: 'null' + title: The task ID this span is associated with + description: ID of the task this span belongs to + parent_id: + anyOf: + - type: string + - type: 'null' + title: The parent span ID if this is a child span + description: ID of the parent span if this is a child span in a trace + name: + type: string + title: The name of the span + description: Name that describes what operation this span represents + start_time: + type: string + format: date-time + title: The start time of the span + description: The time the span started + end_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The end time of the span + description: The time the span ended + input: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The input data for the span + description: Input parameters or data for the operation + output: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The output data from the span + description: Output data resulting from the operation + data: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: Additional data associated with the span + description: Any additional metadata or context for the span + type: object + required: + - trace_id + - name + - start_time + title: CreateSpanRequest + CreateStateRequest: + properties: + task_id: + type: string + title: The unique id of the task to send the state to + agent_id: + type: string + title: The unique id of the agent to send the state to + state: + additionalProperties: true + type: object + title: The state to send to the task. + type: object + required: + - task_id + - agent_id + - state + title: CreateStateRequest + CreateTaskMessageRequest: + properties: + task_id: + type: string + title: The unique id of the task to send the message to + content: + $ref: '#/components/schemas/TaskMessageContent' + title: The message to send to the task. + streaming_status: + anyOf: + - type: string + enum: + - IN_PROGRESS + - DONE + - type: 'null' + title: The streaming status of the message + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Optional caller-supplied creation timestamp + description: Optional timestamp for the message. Workflow callers should + pass workflow.now() (Temporal's deterministic monotonic clock) so that + two awaited messages.create calls from the same workflow are guaranteed + to have monotonic timestamps regardless of HTTP scheduling at the server. + If omitted, the server's wall clock at insert time is used. + type: object + required: + - task_id + - content + title: CreateTaskMessageRequest + CreateTaskRequest: + properties: + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: 'Optional human-readable name for the task. When set it must + be globally unique. task/create is get-or-create by name: reusing an existing + name returns the existing task (with its prior history) instead of creating + a new one, so omit name (or make it unique, e.g. by appending a UUID) + whenever each call should produce a fresh task.' + params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Params + description: The parameters for the task. On a get-or-create by name, providing + params overwrites the existing task's params (it is not a pure read). + task_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task Metadata + description: Caller-provided metadata to persist on the task row. Only applied + at task creation; ignored if a task with this name already exists. Forwarded + to the agent inside the ACP payload for backward compatibility. + type: object + title: CreateTaskRequest + DataContent: + properties: + type: + type: string + const: data + title: Type + description: The type of the message, in this case `data`. + default: data + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + data: + additionalProperties: true + type: object + title: Data + description: The contents of the data message. + type: object + required: + - author + - data + title: DataContent + DataContentEntity: + properties: + type: + type: string + const: data + title: Type + description: The type of the message, in this case `data`. + default: data + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + data: + additionalProperties: true + type: object + title: Data + description: The contents of the data message. + type: object + required: + - author + - data + title: DataContentEntity + DataDelta: + properties: + type: + type: string + const: data + title: Type + default: data + data_delta: + anyOf: + - type: string + - type: 'null' + title: Data Delta + default: '' + type: object + title: DataDelta + description: Delta for data updates + DeleteResponse: + properties: + id: + type: string + title: Id + message: + type: string + title: Message + type: object + required: + - id + - message + title: DeleteResponse + DeleteThreadRequest: + properties: + thread_id: + type: string + title: Thread ID + type: object + required: + - thread_id + title: DeleteThreadRequest + Deployment: + properties: + id: + type: string + title: Id + description: The unique identifier of the deployment. + agent_id: + type: string + title: Agent Id + description: The agent this deployment belongs to. + docker_image: + type: string + title: Docker Image + description: Full Docker image URI. + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: Git/build metadata from the agent pod. + status: + $ref: '#/components/schemas/DeploymentStatus' + description: Current deployment status. + acp_url: + anyOf: + - type: string + - type: 'null' + title: Acp Url + description: ACP URL set when agent registers. + is_production: + type: boolean + title: Is Production + description: Whether this is the production deployment. + sgp_deploy_id: + anyOf: + - type: string + - type: 'null' + title: Sgp Deploy Id + description: Correlates to SGP's agentex_deploys.id. + helm_release_name: + anyOf: + - type: string + - type: 'null' + title: Helm Release Name + description: Helm release name for cleanup. + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: When the deployment was created. + promoted_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Promoted At + description: When promoted to production. + expires_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Expires At + description: When marked for cleanup. + type: object + required: + - id + - agent_id + - docker_image + - status + - is_production + title: Deployment + DeploymentHistory: + properties: + id: + type: string + title: Id + description: The unique identifier of the deployment record + agent_id: + type: string + title: Agent Id + description: The ID of the agent this deployment belongs to + author_name: + type: string + title: Author Name + description: Name of the commit author + author_email: + type: string + title: Author Email + description: Email of the commit author + branch_name: + type: string + title: Branch Name + description: Name of the branch + build_timestamp: + type: string + format: date-time + title: Build Timestamp + description: When the build was created + deployment_timestamp: + type: string + format: date-time + title: Deployment Timestamp + description: When this deployment was first seen in the system + commit_hash: + type: string + title: Commit Hash + description: Git commit hash for this deployment + type: object + required: + - id + - agent_id + - author_name + - author_email + - branch_name + - build_timestamp + - deployment_timestamp + - commit_hash + title: DeploymentHistory + description: API schema for deployment history. + DeploymentStatus: + type: string + enum: + - Pending + - Ready + - Failed + title: DeploymentStatus + Event: + properties: + id: + type: string + title: Id + description: The UUID of the event + sequence_id: + type: integer + title: Sequence Id + description: The sequence ID of the event + task_id: + type: string + title: Task Id + description: The UUID of the task that the event belongs to + agent_id: + type: string + title: Agent Id + description: The UUID of the agent that the event belongs to + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: The timestamp of the event + content: + anyOf: + - $ref: '#/components/schemas/TaskMessageContent' + - type: 'null' + description: The content of the event + type: object + required: + - id + - sequence_id + - task_id + - agent_id + title: Event + ExportTaskResponse: + properties: + task_id: + type: string + title: Task Id + messages: + items: + $ref: '#/components/schemas/TaskMessageEntity' + type: array + title: Messages + task_states: + items: + $ref: '#/components/schemas/StateEntity' + type: array + title: Task States + type: object + required: + - task_id + title: ExportTaskResponse + description: Wire format mirrors the entity directly — schema parity is intentional. + ExportTaskToUrlRequest: + properties: + upload_url: + type: string + maxLength: 2083 + minLength: 1 + format: uri + title: Upload Url + description: Presigned PUT URL where Agentex will upload the task snapshot + as JSON. Must be https; must resolve to a public address. + type: object + required: + - upload_url + title: ExportTaskToUrlRequest + ExportTaskToUrlResponse: + properties: + task_id: + type: string + title: Task Id + upload_url: + type: string + title: Upload Url + uploaded_bytes: + type: integer + title: Uploaded Bytes + messages_count: + type: integer + title: Messages Count + task_states_count: + type: integer + title: Task States Count + type: object + required: + - task_id + - upload_url + - uploaded_bytes + - messages_count + - task_states_count + title: ExportTaskToUrlResponse + FileAttachment: + properties: + file_id: + type: string + title: File Id + description: The unique ID of the attached file + name: + type: string + title: Name + description: The name of the file + size: + type: integer + title: Size + description: The size of the file in bytes + type: + type: string + title: Type + description: The MIME type or content type of the file + type: object + required: + - file_id + - name + - size + - type + title: FileAttachment + description: Represents a file attachment in messages. + FileAttachmentEntity: + properties: + file_id: + type: string + title: File Id + description: The unique ID of the attached file + name: + type: string + title: Name + description: The name of the file + size: + type: integer + title: Size + description: The size of the file in bytes + type: + type: string + title: Type + description: The MIME type or content type of the file + type: object + required: + - file_id + - name + - size + - type + title: FileAttachmentEntity + description: Represents a file attachment in messages. + GetCheckpointTupleRequest: + properties: + thread_id: + type: string + title: Thread ID + checkpoint_ns: + type: string + title: Checkpoint namespace + default: '' + checkpoint_id: + anyOf: + - type: string + - type: 'null' + title: Checkpoint ID (None = latest) + type: object + required: + - thread_id + title: GetCheckpointTupleRequest + HTTPValidationError: + properties: + detail: + items: + $ref: '#/components/schemas/ValidationError' + type: array + title: Detail + type: object + title: HTTPValidationError + ListCheckpointsRequest: + properties: + thread_id: + type: string + title: Thread ID + checkpoint_ns: + anyOf: + - type: string + - type: 'null' + title: Checkpoint namespace + before_checkpoint_id: + anyOf: + - type: string + - type: 'null' + title: Before checkpoint ID + filter_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Metadata filter (JSONB @>) + limit: + type: integer + maximum: 1000.0 + minimum: 1.0 + title: Max results + default: 100 + type: object + required: + - thread_id + title: ListCheckpointsRequest + MessageAuthor: + type: string + enum: + - user + - agent + title: MessageAuthor + MessageStyle: + type: string + enum: + - static + - active + title: MessageStyle + PaginatedMessagesResponse: + properties: + data: + items: + $ref: '#/components/schemas/TaskMessage' + type: array + title: Data + description: List of messages + next_cursor: + anyOf: + - type: string + - type: 'null' + title: Next Cursor + description: Cursor for fetching the next page of older messages + has_more: + type: boolean + title: Has More + description: Whether there are more messages to fetch + default: false + type: object + required: + - data + title: PaginatedMessagesResponse + description: Response with cursor pagination metadata. + PauseScheduleRequest: + properties: + note: + anyOf: + - type: string + - type: 'null' + title: Note + description: Optional note explaining why the schedule was paused + type: object + title: PauseScheduleRequest + description: Request model for pausing a schedule + PutCheckpointRequest: + properties: + thread_id: + type: string + title: Thread ID + checkpoint_ns: + type: string + title: Checkpoint namespace + default: '' + checkpoint_id: + type: string + title: Checkpoint ID + parent_checkpoint_id: + anyOf: + - type: string + - type: 'null' + title: Parent checkpoint ID + checkpoint: + additionalProperties: true + type: object + title: Checkpoint JSONB payload + metadata: + additionalProperties: true + type: object + title: Checkpoint metadata + blobs: + items: + $ref: '#/components/schemas/BlobData' + type: array + title: Channel blob data + type: object + required: + - thread_id + - checkpoint_id + - checkpoint + title: PutCheckpointRequest + PutCheckpointResponse: + properties: + thread_id: + type: string + title: Thread Id + checkpoint_ns: + type: string + title: Checkpoint Ns + checkpoint_id: + type: string + title: Checkpoint Id + type: object + required: + - thread_id + - checkpoint_ns + - checkpoint_id + title: PutCheckpointResponse + PutWritesRequest: + properties: + thread_id: + type: string + title: Thread ID + checkpoint_ns: + type: string + title: Checkpoint namespace + default: '' + checkpoint_id: + type: string + title: Checkpoint ID + writes: + items: + $ref: '#/components/schemas/WriteData' + type: array + title: Write data + upsert: + type: boolean + title: Upsert mode + default: false + type: object + required: + - thread_id + - checkpoint_id + - writes + title: PutWritesRequest + ReasoningContent: + properties: + type: + type: string + const: reasoning + title: Type + description: The type of the message, in this case `reasoning`. + default: reasoning + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + summary: + items: + type: string + type: array + title: Summary + description: A list of short reasoning summaries + content: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Content + description: The reasoning content or chain-of-thought text + type: object + required: + - author + - summary + title: ReasoningContent + ReasoningContentDelta: + properties: + type: + type: string + const: reasoning_content + title: Type + default: reasoning_content + content_index: + type: integer + title: Content Index + content_delta: + anyOf: + - type: string + - type: 'null' + title: Content Delta + default: '' + type: object + required: + - content_index + title: ReasoningContentDelta + description: Delta for reasoning content updates + ReasoningContentEntity: + properties: + type: + type: string + const: reasoning + title: Type + description: The type of the message, in this case `reasoning`. + default: reasoning + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + summary: + items: + type: string + type: array + title: Summary + description: A list of short reasoning summaries + content: + anyOf: + - items: + type: string + type: array + - type: 'null' + title: Content + description: The reasoning content or chain-of-thought text + type: object + required: + - author + - summary + title: ReasoningContentEntity + ReasoningSummaryDelta: + properties: + type: + type: string + const: reasoning_summary + title: Type + default: reasoning_summary + summary_index: + type: integer + title: Summary Index + summary_delta: + anyOf: + - type: string + - type: 'null' + title: Summary Delta + default: '' + type: object + required: + - summary_index + title: ReasoningSummaryDelta + description: Delta for reasoning summary updates + RegisterAgentRequest: + properties: + name: + type: string + pattern: ^[a-z0-9-]+$ + title: Name + description: The unique name of the agent. + description: + type: string + title: Description + description: The description of the agent. + acp_url: + type: string + title: Acp Url + description: The URL of the ACP server for the agent. + agent_id: + anyOf: + - type: string + - type: 'null' + title: Agent Id + description: Optional agent ID if the agent already exists and needs to + be updated. + acp_type: + $ref: '#/components/schemas/ACPType' + description: The type of ACP to use for the agent. + principal_context: + anyOf: + - {} + - type: 'null' + title: Principal Context + description: Principal used for authorization + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: The metadata for the agent's registration. + agent_input_type: + anyOf: + - $ref: '#/components/schemas/AgentInputType' + - type: 'null' + description: The type of input the agent expects. + type: object + required: + - name + - description + - acp_url + - acp_type + title: RegisterAgentRequest + RegisterAgentResponse: + properties: + id: + type: string + title: Id + description: The unique identifier of the agent. + name: + type: string + title: Name + description: The unique name of the agent. + description: + type: string + title: Description + description: The description of the action. + status: + $ref: '#/components/schemas/AgentStatus' + description: The status of the action, indicating if it's building, ready, + failed, etc. + default: Unknown + acp_type: + $ref: '#/components/schemas/ACPType' + description: The type of the ACP Server (Either sync or async) + status_reason: + anyOf: + - type: string + - type: 'null' + title: Status Reason + description: The reason for the status of the action. + created_at: + type: string + format: date-time + title: Created At + description: The timestamp when the agent was created + updated_at: + type: string + format: date-time + title: Updated At + description: The timestamp when the agent was last updated + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: The metadata for the agent's registration. + registered_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Registered At + description: The timestamp when the agent was last registered + agent_input_type: + anyOf: + - $ref: '#/components/schemas/AgentInputType' + - type: 'null' + description: The type of input the agent expects. + production_deployment_id: + anyOf: + - type: string + - type: 'null' + title: Production Deployment Id + description: ID of the current production deployment. + agent_api_key: + anyOf: + - type: string + - type: 'null' + title: Agent Api Key + description: The API key for the agent, if applicable. + type: object + required: + - id + - name + - description + - acp_type + - created_at + - updated_at + title: RegisterAgentResponse + description: Response model for registering an agent. + RegisterBuildRequest: + properties: + name: + type: string + pattern: ^[a-z0-9-]+$ + title: Name + description: The unique name of the agent. + description: + type: string + title: Description + description: The description of the agent. + principal_context: + anyOf: + - {} + - type: 'null' + title: Principal Context + description: Principal used for authorization + registration_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Registration Metadata + description: The metadata for the agent's build registration. + agent_input_type: + anyOf: + - $ref: '#/components/schemas/AgentInputType' + - type: 'null' + description: The type of input the agent expects. + type: object + required: + - name + - description + title: RegisterBuildRequest + description: 'Request model for registering an agent at build time (pre-deploy). + + + Unlike RegisterAgentRequest, there is no acp_url (the agent is not running + + yet) and no acp_type is required. The created agent is left in BUILD_ONLY + + status so it can be permissioned/shared before it is deployed.' + RehydrateTaskRequest: + properties: + task_id: + type: string + title: Task Id + messages: + items: + $ref: '#/components/schemas/TaskMessageEntity' + type: array + title: Messages + task_states: + items: + $ref: '#/components/schemas/StateEntity' + type: array + title: Task States + snapshot_url: + anyOf: + - type: string + maxLength: 2083 + minLength: 1 + format: uri + - type: 'null' + title: Snapshot Url + description: Presigned GET URL whose body is a JSON-encoded TaskSnapshotEntity. + Must be https; must resolve to a public address. When set, messages/task_states + must be empty. + type: object + required: + - task_id + title: RehydrateTaskRequest + description: 'Either provide inline content (messages + task_states) or a snapshot_url + + pointing at a presigned JSON download. Mixing both is rejected. + + + The inline form is the canonical shape used by export''s GET response, so + + snapshot → clean → rehydrate round-trips cleanly without serialization + + changes.' + ScheduleActionInfo: + properties: + workflow_name: + type: string + title: Workflow Name + description: Name of the workflow being executed + workflow_id_prefix: + type: string + title: Workflow ID Prefix + description: Prefix for workflow execution IDs + task_queue: + type: string + title: Task Queue + description: Task queue for the workflow + workflow_params: + anyOf: + - items: {} + type: array + - type: 'null' + title: Workflow Parameters + description: Parameters passed to the workflow + type: object + required: + - workflow_name + - workflow_id_prefix + - task_queue + title: ScheduleActionInfo + description: Information about the scheduled action + ScheduleListItem: + properties: + schedule_id: + type: string + title: Schedule ID + description: Unique identifier for the schedule + name: + type: string + title: Schedule Name + description: Human-readable name for the schedule + agent_id: + type: string + title: Agent ID + description: ID of the agent this schedule belongs to + state: + $ref: '#/components/schemas/ScheduleState' + title: State + description: Current state of the schedule + workflow_name: + anyOf: + - type: string + - type: 'null' + title: Workflow Name + description: Name of the scheduled workflow + next_action_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Next Action Time + description: Next scheduled execution time + type: object + required: + - schedule_id + - name + - agent_id + - state + title: ScheduleListItem + description: Abbreviated schedule info for list responses + ScheduleListResponse: + properties: + schedules: + items: + $ref: '#/components/schemas/ScheduleListItem' + type: array + title: Schedules + description: List of schedules + total: + type: integer + title: Total + description: Total number of schedules + type: object + required: + - schedules + - total + title: ScheduleListResponse + description: Response model for listing schedules + ScheduleResponse: + properties: + schedule_id: + type: string + title: Schedule ID + description: Unique identifier for the schedule + name: + type: string + title: Schedule Name + description: Human-readable name for the schedule + agent_id: + type: string + title: Agent ID + description: ID of the agent this schedule belongs to + state: + $ref: '#/components/schemas/ScheduleState' + title: State + description: Current state of the schedule + action: + $ref: '#/components/schemas/ScheduleActionInfo' + title: Action + spec: + $ref: '#/components/schemas/ScheduleSpecInfo' + title: Spec + description: Schedule specification + num_actions_taken: + type: integer + title: Number of Actions Taken + description: Number of times the schedule has executed + default: 0 + num_actions_missed: + type: integer + title: Number of Actions Missed + description: Number of scheduled executions that were missed + default: 0 + next_action_times: + items: + type: string + format: date-time + type: array + title: Next Action Times + description: Upcoming scheduled execution times + last_action_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Last Action Time + description: When the schedule last executed + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: When the schedule was created + type: object + required: + - schedule_id + - name + - agent_id + - state + - action + - spec + title: ScheduleResponse + description: Response model for schedule operations + ScheduleSpecInfo: + properties: + cron_expressions: + items: + type: string + type: array + title: Cron Expressions + description: Cron expressions for the schedule + intervals_seconds: + items: + type: integer + type: array + title: Interval Seconds + description: Interval specifications in seconds + start_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Start At + description: When the schedule starts being active + end_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: End At + description: When the schedule stops being active + type: object + title: ScheduleSpecInfo + description: Information about the schedule specification + ScheduleState: + type: string + enum: + - ACTIVE + - PAUSED + title: ScheduleState + description: Schedule state enum + SendEventRequest: + properties: + task_id: + anyOf: + - type: string + - type: 'null' + title: Task Id + description: The ID of the task that the event was sent to + task_name: + anyOf: + - type: string + - type: 'null' + title: Task Name + description: The name of the task that the event was sent to + content: + anyOf: + - $ref: '#/components/schemas/TaskMessageContent' + - type: 'null' + description: The content to send to the event + type: object + title: SendEventRequest + SendMessageRequest: + properties: + task_id: + anyOf: + - type: string + - type: 'null' + title: Task Id + description: The ID of the task that the message was sent to + task_name: + anyOf: + - type: string + - type: 'null' + title: Task Name + description: The name of the task that the message was sent to + content: + $ref: '#/components/schemas/TaskMessageContent' + description: The message that was sent to the agent + stream: + type: boolean + title: Stream + description: Whether to stream the response message back to the client + default: false + task_params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task Params + description: The parameters for the task (only used when creating new tasks) + type: object + required: + - content + title: SendMessageRequest + Span: + properties: + id: + type: string + title: Unique Span ID + trace_id: + type: string + title: The trace ID for this span + description: Unique identifier for the trace this span belongs to + task_id: + anyOf: + - type: string + - type: 'null' + title: The task ID this span is associated with + description: ID of the task this span belongs to + parent_id: + anyOf: + - type: string + - type: 'null' + title: The parent span ID if this is a child span + description: ID of the parent span if this is a child span in a trace + name: + type: string + title: The name of the span + description: Name that describes what operation this span represents + start_time: + type: string + format: date-time + title: The start time of the span + description: The time the span started + end_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The end time of the span + description: The time the span ended + input: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The input data for the span + description: Input parameters or data for the operation + output: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The output data from the span + description: Output data resulting from the operation + data: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: Additional data associated with the span + description: Any additional metadata or context for the span + type: object + required: + - id + - trace_id + - name + - start_time + title: Span + State: + properties: + task_id: + type: string + title: The unique id of the task to send the state to + agent_id: + type: string + title: The unique id of the agent to send the state to + state: + additionalProperties: true + type: object + title: The state to send to the task. + id: + type: string + title: Id + description: The task state's unique id + created_at: + type: string + format: date-time + title: Created At + description: The timestamp when the state was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: The timestamp when the state was last updated + type: object + required: + - task_id + - agent_id + - state + - id + - created_at + title: State + description: 'Represents a state in the agent system. A state is associated + uniquely with a task and an agent. + + + This entity is used to store states in MongoDB, with each state + + associated with a specific task and agent. The combination of task_id and + agent_id is globally unique. + + + The state is a dictionary of arbitrary data.' + StateEntity: + properties: + id: + anyOf: + - type: string + - type: 'null' + title: Id + description: The task state's unique id + task_id: + type: string + title: Task Id + description: ID of the task this state belongs to. The combination of task_id + and agent_id is globally unique. + agent_id: + type: string + title: Agent Id + description: ID of the agent this state belongs to. The combination of task_id + and agent_id is globally unique. + state: + additionalProperties: true + type: object + title: State + description: The state object that contains arbitrary data + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: The timestamp when the state was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: The timestamp when the state was last updated + type: object + required: + - task_id + - agent_id + - state + title: StateEntity + description: 'Represents a state in the agent system. A state is associated + uniquely with a task and an agent. + + + This entity is used to store states in MongoDB, with each state + + associated with a specific task and agent. The combination of task_id and + agent_id is globally unique. + + + The state is a dictionary of arbitrary data.' + StreamTaskMessageDelta: + properties: + type: + type: string + const: delta + title: Type + default: delta + index: + anyOf: + - type: integer + - type: 'null' + title: Index + parent_task_message: + anyOf: + - $ref: '#/components/schemas/TaskMessage' + - type: 'null' + delta: + anyOf: + - $ref: '#/components/schemas/TaskMessageDelta' + - type: 'null' + type: object + title: StreamTaskMessageDelta + description: Event for streaming chunks of content + StreamTaskMessageDone: + properties: + type: + type: string + const: done + title: Type + default: done + index: + anyOf: + - type: integer + - type: 'null' + title: Index + parent_task_message: + anyOf: + - $ref: '#/components/schemas/TaskMessage' + - type: 'null' + type: object + title: StreamTaskMessageDone + description: Event for indicating the task is done + StreamTaskMessageFull: + properties: + type: + type: string + const: full + title: Type + default: full + index: + anyOf: + - type: integer + - type: 'null' + title: Index + parent_task_message: + anyOf: + - $ref: '#/components/schemas/TaskMessage' + - type: 'null' + content: + $ref: '#/components/schemas/TaskMessageContent' + type: object + required: + - content + title: StreamTaskMessageFull + description: Event for streaming the full content + StreamTaskMessageStart: + properties: + type: + type: string + const: start + title: Type + default: start + index: + anyOf: + - type: integer + - type: 'null' + title: Index + parent_task_message: + anyOf: + - $ref: '#/components/schemas/TaskMessage' + - type: 'null' + content: + $ref: '#/components/schemas/TaskMessageContent' + type: object + required: + - content + title: StreamTaskMessageStart + description: Event for starting a streaming message + Task: + properties: + id: + type: string + title: Unique Task ID + name: + anyOf: + - type: string + - type: 'null' + title: Unique name of the task + status: + anyOf: + - $ref: '#/components/schemas/TaskStatus' + - type: 'null' + title: The current status of the task + status_reason: + anyOf: + - type: string + - type: 'null' + title: The reason for the current task status + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task was last updated + cleaned_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task's content was cleaned for retention compliance; + null when active + params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task parameters + task_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task metadata + type: object + required: + - id + title: Task + TaskMessage: + properties: + id: + anyOf: + - type: string + - type: 'null' + title: Id + description: The task message's unique id + task_id: + type: string + title: Task Id + description: ID of the task this message belongs to + content: + $ref: '#/components/schemas/TaskMessageContent' + description: The content of the message. This content is not OpenAI compatible. + These are messages that are meant to be displayed to the user. + streaming_status: + anyOf: + - type: string + enum: + - IN_PROGRESS + - DONE + - type: 'null' + title: In case of streaming, this indicates whether the message is still + being streamed or has been completed + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: The timestamp when the message was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: The timestamp when the message was last updated + type: object + required: + - task_id + - content + title: TaskMessage + description: 'Represents a message in the agent system. + + + This entity is used to store messages in MongoDB, with each message + + associated with a specific task.' + TaskMessageContent: + oneOf: + - $ref: '#/components/schemas/TextContent' + - $ref: '#/components/schemas/ReasoningContent' + - $ref: '#/components/schemas/DataContent' + - $ref: '#/components/schemas/ToolRequestContent' + - $ref: '#/components/schemas/ToolResponseContent' + title: TaskMessageContent + discriminator: + propertyName: type + mapping: + data: '#/components/schemas/DataContent' + reasoning: '#/components/schemas/ReasoningContent' + text: '#/components/schemas/TextContent' + tool_request: '#/components/schemas/ToolRequestContent' + tool_response: '#/components/schemas/ToolResponseContent' + TaskMessageDelta: + oneOf: + - $ref: '#/components/schemas/TextDelta' + - $ref: '#/components/schemas/DataDelta' + - $ref: '#/components/schemas/ToolRequestDelta' + - $ref: '#/components/schemas/ToolResponseDelta' + - $ref: '#/components/schemas/ReasoningSummaryDelta' + - $ref: '#/components/schemas/ReasoningContentDelta' + title: TaskMessageDelta + discriminator: + propertyName: type + mapping: + data: '#/components/schemas/DataDelta' + reasoning_content: '#/components/schemas/ReasoningContentDelta' + reasoning_summary: '#/components/schemas/ReasoningSummaryDelta' + text: '#/components/schemas/TextDelta' + tool_request: '#/components/schemas/ToolRequestDelta' + tool_response: '#/components/schemas/ToolResponseDelta' + TaskMessageEntity: + properties: + id: + anyOf: + - type: string + - type: 'null' + title: Id + description: The task message's unique id + task_id: + type: string + title: Task Id + description: ID of the task this message belongs to + content: + oneOf: + - $ref: '#/components/schemas/TextContentEntity' + - $ref: '#/components/schemas/DataContentEntity' + - $ref: '#/components/schemas/ToolRequestContentEntity' + - $ref: '#/components/schemas/ToolResponseContentEntity' + - $ref: '#/components/schemas/ReasoningContentEntity' + title: Content + description: The content of the message. This content is not OpenAI compatible. + These are messages that are meant to be displayed to the user. + discriminator: + propertyName: type + mapping: + data: '#/components/schemas/DataContentEntity' + reasoning: '#/components/schemas/ReasoningContentEntity' + text: '#/components/schemas/TextContentEntity' + tool_request: '#/components/schemas/ToolRequestContentEntity' + tool_response: '#/components/schemas/ToolResponseContentEntity' + streaming_status: + anyOf: + - type: string + enum: + - IN_PROGRESS + - DONE + - type: 'null' + title: In case of streaming, this indicates whether the message is still + being streamed or has been completed + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Created At + description: The timestamp when the message was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: Updated At + description: The timestamp when the message was last updated + type: object + required: + - task_id + - content + title: TaskMessageEntity + description: 'Represents a message in the agent system. + + + This entity is used to store messages in MongoDB, with each message + + associated with a specific task.' + TaskMessageUpdate: + oneOf: + - $ref: '#/components/schemas/StreamTaskMessageStart' + - $ref: '#/components/schemas/StreamTaskMessageDelta' + - $ref: '#/components/schemas/StreamTaskMessageFull' + - $ref: '#/components/schemas/StreamTaskMessageDone' + title: TaskMessageUpdate + discriminator: + propertyName: type + mapping: + delta: '#/components/schemas/StreamTaskMessageDelta' + done: '#/components/schemas/StreamTaskMessageDone' + full: '#/components/schemas/StreamTaskMessageFull' + start: '#/components/schemas/StreamTaskMessageStart' + TaskRelationships: + type: string + enum: + - agents + title: TaskRelationships + description: Task relationships that can be loaded + TaskResponse: + properties: + id: + type: string + title: Unique Task ID + name: + anyOf: + - type: string + - type: 'null' + title: Unique name of the task + status: + anyOf: + - $ref: '#/components/schemas/TaskStatus' + - type: 'null' + title: The current status of the task + status_reason: + anyOf: + - type: string + - type: 'null' + title: The reason for the current task status + created_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task was created + updated_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task was last updated + cleaned_at: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The timestamp when the task's content was cleaned for retention compliance; + null when active + params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task parameters + task_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Task metadata + agents: + anyOf: + - items: + $ref: '#/components/schemas/Agent' + type: array + - type: 'null' + title: Agents associated with this task (only populated when 'agent' view + is requested) + type: object + required: + - id + title: TaskResponse + description: Task response model with optional related data based on relationships + TaskStatus: + type: string + enum: + - CANCELED + - COMPLETED + - FAILED + - RUNNING + - TERMINATED + - TIMED_OUT + - DELETED + title: TaskStatus + TaskStatusReasonRequest: + properties: + reason: + anyOf: + - type: string + - type: 'null' + title: Optional reason for the status change + type: object + title: TaskStatusReasonRequest + TextContent: + properties: + type: + type: string + const: text + title: Type + description: The type of the message, in this case `text`. + default: text + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + format: + $ref: '#/components/schemas/TextFormat' + description: The format of the message. This is used by the client to determine + how to display the message. + default: plain + content: + type: string + title: Content + description: The contents of the text message. + attachments: + anyOf: + - items: + $ref: '#/components/schemas/FileAttachment' + type: array + - type: 'null' + title: Attachments + description: Optional list of file attachments with structured metadata. + type: object + required: + - author + - content + title: TextContent + TextContentEntity: + properties: + type: + type: string + const: text + title: Type + description: The type of the message, in this case `text`. + default: text + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + format: + $ref: '#/components/schemas/TextFormat' + description: The format of the message. This is used by the client to determine + how to display the message. + default: plain + content: + type: string + title: Content + description: The contents of the text message. + attachments: + anyOf: + - items: + $ref: '#/components/schemas/FileAttachmentEntity' + type: array + - type: 'null' + title: Attachments + description: Optional list of file attachments with structured metadata. + type: object + required: + - author + - content + title: TextContentEntity + TextDelta: + properties: + type: + type: string + const: text + title: Type + default: text + text_delta: + anyOf: + - type: string + - type: 'null' + title: Text Delta + default: '' + type: object + title: TextDelta + description: Delta for text updates + TextFormat: + type: string + enum: + - markdown + - plain + - code + title: TextFormat + ToolRequestContent: + properties: + type: + type: string + const: tool_request + title: Type + description: The type of the message, in this case `tool_request`. + default: tool_request + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + tool_call_id: + type: string + title: Tool Call Id + description: The ID of the tool call that is being requested. + name: + type: string + title: Name + description: The name of the tool that is being requested. + arguments: + additionalProperties: true + type: object + title: Arguments + description: The arguments to the tool. + type: object + required: + - author + - tool_call_id + - name + - arguments + title: ToolRequestContent + ToolRequestContentEntity: + properties: + type: + type: string + const: tool_request + title: Type + description: The type of the message, in this case `tool_request`. + default: tool_request + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + tool_call_id: + type: string + title: Tool Call Id + description: The ID of the tool call that is being requested. + name: + type: string + title: Name + description: The name of the tool that is being requested. + arguments: + additionalProperties: true + type: object + title: Arguments + description: The arguments to the tool. + type: object + required: + - author + - tool_call_id + - name + - arguments + title: ToolRequestContentEntity + ToolRequestDelta: + properties: + type: + type: string + const: tool_request + title: Type + default: tool_request + tool_call_id: + type: string + title: Tool Call Id + name: + type: string + title: Name + arguments_delta: + anyOf: + - type: string + - type: 'null' + title: Arguments Delta + default: '' + type: object + required: + - tool_call_id + - name + title: ToolRequestDelta + description: Delta for tool request updates + ToolResponseContent: + properties: + type: + type: string + const: tool_response + title: Type + description: The type of the message, in this case `tool_response`. + default: tool_response + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + tool_call_id: + type: string + title: Tool Call Id + description: The ID of the tool call that is being responded to. + name: + type: string + title: Name + description: The name of the tool that is being responded to. + content: + title: Content + description: The result of the tool. + type: object + required: + - author + - tool_call_id + - name + - content + title: ToolResponseContent + ToolResponseContentEntity: + properties: + type: + type: string + const: tool_response + title: Type + description: The type of the message, in this case `tool_response`. + default: tool_response + author: + $ref: '#/components/schemas/MessageAuthor' + description: The role of the messages author, in this case `system`, `user`, + `assistant`, or `tool`. + style: + $ref: '#/components/schemas/MessageStyle' + description: The style of the message. This is used by the client to determine + how to display the message. + default: static + tool_call_id: + type: string + title: Tool Call Id + description: The ID of the tool call that is being responded to. + name: + type: string + title: Name + description: The name of the tool that is being responded to. + content: + title: Content + description: The result of the tool. + type: object + required: + - author + - tool_call_id + - name + - content + title: ToolResponseContentEntity + ToolResponseDelta: + properties: + type: + type: string + const: tool_response + title: Type + default: tool_response + tool_call_id: + type: string + title: Tool Call Id + name: + type: string + title: Name + content_delta: + anyOf: + - type: string + - type: 'null' + title: Content Delta + default: '' + type: object + required: + - tool_call_id + - name + title: ToolResponseDelta + description: Delta for tool response updates + UnpauseScheduleRequest: + properties: + note: + anyOf: + - type: string + - type: 'null' + title: Note + description: Optional note explaining why the schedule was unpaused + type: object + title: UnpauseScheduleRequest + description: Request model for unpausing a schedule + UpdateAgentTaskTrackerRequest: + properties: + last_processed_event_id: + anyOf: + - type: string + - type: 'null' + title: Last Processed Event Id + description: The most recent processed event ID (omit to leave unchanged) + status: + anyOf: + - type: string + - type: 'null' + title: Status + description: Processing status + status_reason: + anyOf: + - type: string + - type: 'null' + title: Status Reason + description: Optional status reason + type: object + title: UpdateAgentTaskTrackerRequest + description: Request model for updating an agent task tracker. + UpdateSpanRequest: + properties: + trace_id: + anyOf: + - type: string + - type: 'null' + title: The trace ID for this span + description: Unique identifier for the trace this span belongs to + task_id: + anyOf: + - type: string + - type: 'null' + title: The task ID this span is associated with + description: ID of the task this span belongs to + parent_id: + anyOf: + - type: string + - type: 'null' + title: The parent span ID if this is a child span + description: ID of the parent span if this is a child span in a trace + name: + anyOf: + - type: string + - type: 'null' + title: The name of the span + description: Name that describes what operation this span represents + start_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The start time of the span + description: The time the span started + end_time: + anyOf: + - type: string + format: date-time + - type: 'null' + title: The end time of the span + description: The time the span ended + input: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The input data for the span + description: Input parameters or data for the operation + output: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: The output data from the span + description: Output data resulting from the operation + data: + anyOf: + - additionalProperties: true + type: object + - items: + additionalProperties: true + type: object + type: array + - type: 'null' + title: Additional data associated with the span + description: Any additional metadata or context for the span + type: object + title: UpdateSpanRequest + UpdateStateRequest: + properties: + task_id: + type: string + title: The unique id of the task to update the state of + agent_id: + type: string + title: The unique id of the agent to update the state of + state: + additionalProperties: true + type: object + title: The state to update the state with. + type: object + required: + - task_id + - agent_id + - state + title: UpdateStateRequest + UpdateTaskMessageRequest: + properties: + task_id: + type: string + title: The unique id of the task to update the message of + content: + $ref: '#/components/schemas/TaskMessageContent' + title: The message to update the message with. + streaming_status: + anyOf: + - type: string + enum: + - IN_PROGRESS + - DONE + - type: 'null' + title: The streaming status of the message + type: object + required: + - task_id + - content + title: UpdateTaskMessageRequest + UpdateTaskRequest: + properties: + task_metadata: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: If provided, replaces task_metadata with this value + type: object + title: UpdateTaskRequest + ValidationError: + properties: + loc: + items: + anyOf: + - type: string + - type: integer + type: array + title: Location + msg: + type: string + title: Message + type: + type: string + title: Error Type + input: + title: Input + ctx: + type: object + title: Context + type: object + required: + - loc + - msg + - type + title: ValidationError + WriteData: + properties: + task_id: + type: string + title: Task ID + idx: + type: integer + title: Write index + channel: + type: string + title: Channel name + type: + anyOf: + - type: string + - type: 'null' + title: Serialization type tag + blob: + type: string + title: Base64-encoded binary data + task_path: + type: string + title: Task path + default: '' + type: object + required: + - task_id + - idx + - channel + - blob + title: WriteData + WriteResponse: + properties: + task_id: + type: string + title: Task Id + idx: + type: integer + title: Idx + channel: + type: string + title: Channel + type: + anyOf: + - type: string + - type: 'null' + title: Type + blob: + anyOf: + - type: string + - type: 'null' + title: Blob + type: object + required: + - task_id + - idx + - channel + title: WriteResponse diff --git a/tests/compat/test_request_compat.py b/tests/compat/test_request_compat.py new file mode 100644 index 000000000..9a6a62deb --- /dev/null +++ b/tests/compat/test_request_compat.py @@ -0,0 +1,129 @@ +"""Validate that ADK requests stay valid against a window of supported server +OpenAPI contracts (server_specs/); see server_specs/manifest.json for the window.""" + +from __future__ import annotations + +import json +from typing import Any +from pathlib import Path +from unittest.mock import Mock + +import yaml +import httpx +import pytest +from jsonschema import Draft202012Validator +from referencing import Registry, Resource +from referencing.jsonschema import DRAFT202012 + +from agentex import AsyncAgentex +from agentex.lib.core.services.adk.state import StateService + +_SPEC_DIR = Path(__file__).parent / "server_specs" +_BASE_URL = "http://127.0.0.1:4010" +_STATE_RESPONSE = { + "id": "s1", + "agent_id": "a1", + "task_id": "t1", + "state": {"k": "v"}, + "created_at": "2026-05-13T18:30:00Z", +} + + +def _window() -> list[dict[str, Any]]: + manifest = json.loads((_SPEC_DIR / "manifest.json").read_text()) + return [ + {"label": e["label"], "spec": yaml.safe_load((_SPEC_DIR / e["file"]).read_text())} for e in manifest["specs"] + ] + + +def _mock_span(): + span = Mock() + span.output = None + + async def __aenter__(_self): + return span + + async def __aexit__(_self, *args): + return None + + span.__aenter__ = __aenter__ + span.__aexit__ = __aexit__ + return span + + +def _state_service(client: AsyncAgentex) -> StateService: + tracer = Mock() + trace = Mock() + trace.span.return_value = _mock_span() + tracer.trace.return_value = trace + return StateService(agentex_client=client, tracer=tracer) + + +async def _drive_update(svc: StateService) -> None: + await svc.update_state(state_id="s1", task_id="t1", agent_id="a1", state={"k": "v"}) + + +async def _drive_create(svc: StateService) -> None: + await svc.create_state(task_id="t1", agent_id="a1", state={"k": "v"}) + + +# Each ADK operation: how to drive it, the request it emits, and the server-spec +# operation (path template + method) whose requestBody its body must satisfy. +_OPERATIONS = [ + { + "label": "states.update", + "http_method": "PUT", + "url": f"{_BASE_URL}/states/s1", + "spec_path": "/states/{state_id}", + "spec_method": "put", + "drive": _drive_update, + }, + { + "label": "states.create", + "http_method": "POST", + "url": f"{_BASE_URL}/states", + "spec_path": "/states", + "spec_method": "post", + "drive": _drive_create, + }, +] + +_WINDOW = _window() + + +def _deref(schema: dict[str, Any], spec: dict[str, Any]) -> dict[str, Any]: + ref = schema.get("$ref") + if not ref or not ref.startswith("#/"): + return schema + node: Any = spec + for part in ref[2:].split("/"): + node = node[part] + return node + + +def _request_body_schema(spec: dict[str, Any], path: str, method: str) -> dict[str, Any]: + schema = spec["paths"][path][method]["requestBody"]["content"]["application/json"]["schema"] + return _deref(schema, spec) + + +@pytest.mark.parametrize("entry", _WINDOW, ids=lambda e: e["label"]) +@pytest.mark.parametrize("op", _OPERATIONS, ids=lambda o: o["label"]) +async def test_adk_request_validates_against_server_spec( + op: dict[str, Any], entry: dict[str, Any], respx_mock: Any +) -> None: + route = respx_mock.route(method=op["http_method"], url=op["url"]).mock( + return_value=httpx.Response(200, json=_STATE_RESPONSE) + ) + async with AsyncAgentex(base_url=_BASE_URL, api_key="test") as client: + await op["drive"](_state_service(client)) + + assert route.called, f"{op['label']} did not hit {op['url']}" + body = json.loads(route.calls.last.request.content) + + spec = entry["spec"] + registry = Registry().with_resource(uri="", resource=Resource(contents=spec, specification=DRAFT202012)) + schema = _request_body_schema(spec, op["spec_path"], op["spec_method"]) + errors = sorted(Draft202012Validator(schema, registry=registry).iter_errors(body), key=str) + assert not errors, f"{op['label']} request {body} violates server contract '{entry['label']}': " + "; ".join( + e.message for e in errors + ) From a5abbb9669c6ab71c52e60db72676c95c20d840d Mon Sep 17 00:00:00 2001 From: Max Parke Date: Wed, 17 Jun 2026 13:59:29 -0400 Subject: [PATCH 4/5] fix(packaging): guard agentex-client surface, bump floor, smoke-test wheel install (#406) Co-authored-by: Claude Opus 4.8 --- .github/workflows/ci.yml | 4 ++++ adk/pyproject.toml | 2 +- scripts/check-wheel-install | 25 +++++++++++++++++++++++++ src/agentex/lib/__init__.py | 4 ++++ src/agentex/lib/_version_guard.py | 28 ++++++++++++++++++++++++++++ tests/lib/test_version_guard.py | 26 ++++++++++++++++++++++++++ uv.lock | 4 ++-- 7 files changed, 90 insertions(+), 3 deletions(-) create mode 100755 scripts/check-wheel-install create mode 100644 src/agentex/lib/_version_guard.py create mode 100644 tests/lib/test_version_guard.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 0c0fa982f..8c96ca356 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -61,6 +61,10 @@ jobs: # force-include can't build via the sdist-then-wheel default. run: uv build --all-packages --wheel + - name: Smoke-test wheel install + # Both wheels must install together into one working agentex.* namespace. + run: ./scripts/check-wheel-install + - name: Get GitHub OIDC Token if: |- github.repository == 'stainless-sdks/agentex-sdk-python' && diff --git a/adk/pyproject.toml b/adk/pyproject.toml index 33132a736..a33f33647 100644 --- a/adk/pyproject.toml +++ b/adk/pyproject.toml @@ -15,7 +15,7 @@ readme = "README.md" dependencies = [ # Co-released in lockstep; floor-only by design — a ceiling would # eventually exclude the co-versioned slim (release-please can't bump it). - "agentex-client>=0.12.0", + "agentex-client>=0.13.0", # CLI surface (agentex.lib.cli.*, agentex.lib.sdk.config.*) "typer>=0.16,<0.17", "questionary>=2.0.1,<3", diff --git a/scripts/check-wheel-install b/scripts/check-wheel-install new file mode 100755 index 000000000..b80aed2d2 --- /dev/null +++ b/scripts/check-wheel-install @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +# Smoke: agentex-client + agentex-sdk must install together into one working +# agentex.* namespace. Builds + installs in a clean temp dir to avoid stale dist/. + +set -euo pipefail + +cd "$(dirname "$0")/.." + +work="$(mktemp -d)" +echo "==> building both wheels into $work/dist" +uv build --all-packages --wheel --out-dir "$work/dist" + +venv="$work/venv" +uv venv "$venv" >/dev/null +echo "==> installing both wheels into a fresh venv" +uv pip install --python "$venv" "$work"/dist/agentex_client-*.whl "$work"/dist/agentex_sdk-*.whl + +echo "==> importing the merged namespace from the installed wheels" +"$venv/bin/python" - <<'PY' +import agentex.lib.adk # ADK overlay — ships in agentex-sdk +from agentex.types import Event # client surface — ships in agentex-client +from agentex.resources import states # client surface that "didn't land" in the incident + +print("agentex namespace OK:", Event.__name__, states.__name__) +PY diff --git a/src/agentex/lib/__init__.py b/src/agentex/lib/__init__.py index e69de29bb..9d960dfee 100644 --- a/src/agentex/lib/__init__.py +++ b/src/agentex/lib/__init__.py @@ -0,0 +1,4 @@ +from agentex.lib._version_guard import verify_client_compatibility + +# Fail fast + clearly on a skewed/incomplete agentex-client install. +verify_client_compatibility() diff --git a/src/agentex/lib/_version_guard.py b/src/agentex/lib/_version_guard.py new file mode 100644 index 000000000..a05572efc --- /dev/null +++ b/src/agentex/lib/_version_guard.py @@ -0,0 +1,28 @@ +"""Fail fast with a clear error on an incomplete agentex-client install instead +of a cryptic `cannot import name ... from agentex.types`.""" + +from __future__ import annotations + +from importlib.metadata import PackageNotFoundError, version + + +def _installed(package: str) -> str: + try: + return version(package) + except PackageNotFoundError: + return "unknown" + + +def verify_client_compatibility() -> None: + # Canary on the client REST surface, not the version: newer clients are fine + # (additive); we only fail if a symbol/resource the ADK needs is absent. + try: + from agentex.types import Event as _Event # noqa: F401 + from agentex.resources import states as _states # noqa: F401 + except (ImportError, AttributeError) as exc: + raise ImportError( + f"agentex-sdk could not import the agentex-client REST surface it " + f"depends on (agentex-sdk={_installed('agentex-sdk')}, " + f"agentex-client={_installed('agentex-client')}). Reinstall both at a " + f"compatible version, e.g. `pip install --force-reinstall agentex-sdk`." + ) from exc diff --git a/tests/lib/test_version_guard.py b/tests/lib/test_version_guard.py new file mode 100644 index 000000000..45bd2be7a --- /dev/null +++ b/tests/lib/test_version_guard.py @@ -0,0 +1,26 @@ +"""Tests for the agentex-client compatibility guard (0.13.0 split regression).""" + +from __future__ import annotations + +import pytest + +import agentex.lib._version_guard as guard + + +def test_passes_when_surface_present() -> None: + guard.verify_client_compatibility() # full client surface installed + + +def test_newer_client_not_rejected(monkeypatch: pytest.MonkeyPatch) -> None: + # Version is not a gate: a newer client (additive) with the full surface passes. + monkeypatch.setattr(guard, "version", lambda pkg: "0.14.0" if pkg == "agentex-client" else "0.13.0") + guard.verify_client_compatibility() + + +def test_raises_when_client_surface_incomplete(monkeypatch: pytest.MonkeyPatch) -> None: + import agentex.types + + # A partial install missing a needed symbol fails with an actionable error. + monkeypatch.delattr(agentex.types, "Event", raising=False) + with pytest.raises(ImportError, match="could not import the agentex-client REST surface"): + guard.verify_client_compatibility() diff --git a/uv.lock b/uv.lock index be3d8bbd8..8a41ba29c 100644 --- a/uv.lock +++ b/uv.lock @@ -15,7 +15,7 @@ members = [ [[package]] name = "agentex-client" -version = "0.12.0" +version = "0.13.0" source = { editable = "." } dependencies = [ { name = "anyio" }, @@ -91,7 +91,7 @@ dev = [ [[package]] name = "agentex-sdk" -version = "0.12.0" +version = "0.13.0" source = { editable = "adk" } dependencies = [ { name = "agentex-client" }, From bbb35e15a91e09f9c38b9b75b31c00c5581e907b Mon Sep 17 00:00:00 2001 From: "stainless-app[bot]" <142633134+stainless-app[bot]@users.noreply.github.com> Date: Wed, 17 Jun 2026 18:01:31 +0000 Subject: [PATCH 5/5] chore: release main --- .release-please-manifest.json | 4 ++-- CHANGELOG.md | 14 ++++++++++++++ adk/CHANGELOG.md | 13 +++++++++++++ adk/pyproject.toml | 2 +- pyproject.toml | 2 +- src/agentex/_version.py | 2 +- 6 files changed, 32 insertions(+), 5 deletions(-) diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 4470737b7..edf7acaa0 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,4 +1,4 @@ { - ".": "0.13.0", - "adk": "0.13.0" + ".": "0.13.1", + "adk": "0.13.1" } diff --git a/CHANGELOG.md b/CHANGELOG.md index 3198ed8f2..abc68a6ba 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,20 @@ * **tracing:** emit OTel metrics for async span queue depth, batch drain, and SGP export success/failure (HTTP status labels). Disable SDK-side recording with ``AGENTEX_TRACING_METRICS=0``. +## 0.13.1 (2026-06-17) + +Full Changelog: [agentex-client-v0.13.0...agentex-client-v0.13.1](https://github.com/scaleapi/scale-agentex-python/compare/agentex-client-v0.13.0...agentex-client-v0.13.1) + +### Bug Fixes + +* **adk:** re-send task_id/agent_id in state updates for backend compatibility ([#405](https://github.com/scaleapi/scale-agentex-python/issues/405)) ([f59f26d](https://github.com/scaleapi/scale-agentex-python/commit/f59f26d4402f01318cf34d57820e121d97719986)) +* **packaging:** guard agentex-client surface, bump floor, smoke-test wheel install ([#406](https://github.com/scaleapi/scale-agentex-python/issues/406)) ([a5abbb9](https://github.com/scaleapi/scale-agentex-python/commit/a5abbb9669c6ab71c52e60db72676c95c20d840d)) + + +### Documentation + +* drop stale keep_files / dashboard-config comments ([#401](https://github.com/scaleapi/scale-agentex-python/issues/401)) ([23858df](https://github.com/scaleapi/scale-agentex-python/commit/23858df775d0a617c6418eed28f1b68c9bf9ed5c)) + ## 0.13.0 (2026-06-10) Full Changelog: [agentex-client-v0.12.0...agentex-client-v0.13.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-client-v0.12.0...agentex-client-v0.13.0) diff --git a/adk/CHANGELOG.md b/adk/CHANGELOG.md index 2f661da4f..70d5c90c9 100644 --- a/adk/CHANGELOG.md +++ b/adk/CHANGELOG.md @@ -1,5 +1,18 @@ # Changelog +## 0.13.1 (2026-06-17) + +Full Changelog: [agentex-sdk-v0.13.0...agentex-sdk-v0.13.1](https://github.com/scaleapi/scale-agentex-python/compare/agentex-sdk-v0.13.0...agentex-sdk-v0.13.1) + +### Bug Fixes + +* **packaging:** guard agentex-client surface, bump floor, smoke-test wheel install ([#406](https://github.com/scaleapi/scale-agentex-python/issues/406)) ([a5abbb9](https://github.com/scaleapi/scale-agentex-python/commit/a5abbb9669c6ab71c52e60db72676c95c20d840d)) + + +### Documentation + +* drop stale keep_files / dashboard-config comments ([#401](https://github.com/scaleapi/scale-agentex-python/issues/401)) ([23858df](https://github.com/scaleapi/scale-agentex-python/commit/23858df775d0a617c6418eed28f1b68c9bf9ed5c)) + ## 0.13.0 (2026-06-10) Full Changelog: [agentex-sdk-v0.12.0...agentex-sdk-v0.13.0](https://github.com/scaleapi/scale-agentex-python/compare/agentex-sdk-v0.12.0...agentex-sdk-v0.13.0) diff --git a/adk/pyproject.toml b/adk/pyproject.toml index a33f33647..729592eb1 100644 --- a/adk/pyproject.toml +++ b/adk/pyproject.toml @@ -4,7 +4,7 @@ # (agentex/{__init__.py, _*.py, types/, resources/}) ships from the slim # sibling package `agentex-client` which is pinned as a runtime dep. name = "agentex-sdk" -version = "0.13.0" +version = "0.13.1" description = "Agent Development Kit (ADK) overlay for the Agentex API — FastACP server, Temporal workflows, LLM provider integrations, observability" license = "Apache-2.0" authors = [ diff --git a/pyproject.toml b/pyproject.toml index 09a61f048..8fdbe0410 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -3,7 +3,7 @@ # overlay (formerly `src/agentex/lib/*`) now lives in `adk/` and ships # as the sibling `agentex-sdk` package — see `adk/pyproject.toml`. name = "agentex-client" -version = "0.13.0" +version = "0.13.1" description = "The official Python REST client for the Agentex API" dynamic = ["readme"] license = "Apache-2.0" diff --git a/src/agentex/_version.py b/src/agentex/_version.py index fd1c37af9..bc927dc30 100644 --- a/src/agentex/_version.py +++ b/src/agentex/_version.py @@ -1,4 +1,4 @@ # File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details. __title__ = "agentex" -__version__ = "0.13.0" # x-release-please-version +__version__ = "0.13.1" # x-release-please-version