From a41096d0e98bf4550f0d68914af198c3c00330e2 Mon Sep 17 00:00:00 2001 From: Declan Brady Date: Tue, 5 May 2026 14:11:05 -0400 Subject: [PATCH 1/5] feat: commit generated OpenAPI spec with CI freshness check Adds agentex/openapi.yaml as the source-of-truth Stainless input, plus a CI job that regenerates the spec on every PR touching agentex/ and fails if the committed file is stale. Downstream consumers (Stainless build workflow in scaleapi/agentex) can read this file directly via the public submodule mirror without re-running spec generation themselves. --- .github/workflows/ci.yml | 48 +- agentex/openapi.yaml | 6040 ++++++++++++++++++++++ agentex/scripts/generate_openapi_spec.py | 45 + 3 files changed, 6131 insertions(+), 2 deletions(-) create mode 100644 agentex/openapi.yaml create mode 100644 agentex/scripts/generate_openapi_spec.py diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e2e83a11..e03fff99 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -167,12 +167,51 @@ jobs: exit 1 fi + openapi-spec: + name: "Verify OpenAPI spec is up to date" + runs-on: ubuntu-latest + needs: changes + if: needs.changes.outputs.agentex == 'true' + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: '3.12' + + - name: Install uv + uses: astral-sh/setup-uv@v4 + with: + version: "0.7.3" + enable-cache: true + + - name: Install dependencies + working-directory: ./agentex + run: uv sync + + - name: Regenerate OpenAPI spec + working-directory: ./agentex + run: uv run --with pyyaml python scripts/generate_openapi_spec.py --output openapi.yaml + + - name: Verify committed spec matches generated spec + working-directory: ./agentex + run: | + if ! git diff --exit-code openapi.yaml; then + echo "❌ The committed openapi.yaml is out of date." + echo "Run 'uv run --with pyyaml python scripts/generate_openapi_spec.py --output openapi.yaml' from agentex/ and commit the result." + exit 1 + fi + echo "✅ openapi.yaml is up to date" + # This job is used as a required status check for branch protection # It will pass if the conditional jobs either passed or were skipped ci-status: name: "CI Status Check" runs-on: ubuntu-latest - needs: [changes, test, docs] + needs: [changes, test, docs, openapi-spec] if: always() steps: - name: Check CI status @@ -191,7 +230,12 @@ jobs: echo "❌ Documentation build failed" exit 1 fi - + + if [ "${{ needs.openapi-spec.result }}" != "success" ]; then + echo "❌ OpenAPI spec freshness check failed" + exit 1 + fi + echo "✅ All checks passed" else echo "No agentex changes detected - skipping tests and docs" diff --git a/agentex/openapi.yaml b/agentex/openapi.yaml new file mode 100644 index 00000000..69b2745e --- /dev/null +++ b/agentex/openapi.yaml @@ -0,0 +1,6040 @@ +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/forward/name/{agent_name}/{path}: + post: + tags: + - Agents + summary: Forward request to agent by ID + description: Forward a request to an agent by its unique ID. + operationId: forward_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' + get: + tags: + - Agents + summary: Forward request to agent by ID + description: Forward a request to an agent by its unique ID. + operationId: forward_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' +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 + 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. + 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 + 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 + type: object + required: + - task_id + - content + title: CreateTaskMessageRequest + CreateTaskRequest: + properties: + name: + anyOf: + - type: string + - type: 'null' + title: Name + description: The name of the task to create + params: + anyOf: + - additionalProperties: true + type: object + - type: 'null' + title: Params + description: The parameters for the task + 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 + 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 + 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. + 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 + 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. + 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.' + 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 + 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' + 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 + 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 + 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 + 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 + 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/agentex/scripts/generate_openapi_spec.py b/agentex/scripts/generate_openapi_spec.py new file mode 100644 index 00000000..6fbfe0ed --- /dev/null +++ b/agentex/scripts/generate_openapi_spec.py @@ -0,0 +1,45 @@ +"""Generate the AgentEx OpenAPI spec to a YAML file for Stainless ingestion. + +Imports the FastAPI app and dumps its OpenAPI schema. The lifespan context +(DB / Temporal / Redis startup) is intentionally not run — we only need the +schema produced by route registration and Pydantic models. +""" + +from __future__ import annotations + +import argparse +import os +from pathlib import Path + +# Provide non-empty defaults for env vars consulted at import time so module +# evaluation does not fail in the CI runner where nothing is configured. +os.environ.setdefault("ENVIRONMENT", "development") +os.environ.setdefault("ALLOWED_ORIGINS", "*") + + +def main() -> int: + package_root = Path(__file__).resolve().parent.parent + parser = argparse.ArgumentParser(description=__doc__) + parser.add_argument( + "--output", + "-o", + default=str(package_root / "openapi.yaml"), + help="Path to write the OpenAPI YAML spec (default: ./openapi.yaml).", + ) + args = parser.parse_args() + + import yaml + from src.api.app import fastapi_app + + spec = fastapi_app.openapi() + output_path = Path(args.output) + output_path.parent.mkdir(parents=True, exist_ok=True) + with output_path.open("w") as f: + yaml.dump(spec, f, sort_keys=False, allow_unicode=True) + + print(f"Wrote OpenAPI spec to {output_path} ({output_path.stat().st_size} bytes)") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) From 07d40e59b0e9ff1900b9025f51e875ab96fbccf8 Mon Sep 17 00:00:00 2001 From: Declan Brady Date: Tue, 5 May 2026 14:17:12 -0400 Subject: [PATCH 2/5] fix: deterministic OpenAPI spec gen + pin pyyaml + CI hardening - Split the dual-method /forward/name route into separate GET and POST handlers. The previous single function with methods=["GET","POST"] produced two operations with identical operationIds, making the generated spec non-deterministic between runs (route iteration order is unstable). - Pin pyyaml as a real dependency (>=6.0,<7) instead of resolving it ad-hoc with --with pyyaml, which would re-resolve to the latest release on every CI run and could spuriously fail the freshness check if pyyaml ships a serialization change. - Add timeout-minutes: 10 to the openapi-spec job so a hung uv sync or app import can't consume the 6-hour default. --- .github/workflows/ci.yml | 5 +++-- agentex/openapi.yaml | 16 ++++++++-------- agentex/pyproject.toml | 1 + agentex/src/api/routes/agents.py | 27 ++++++++++++++++++++++----- 4 files changed, 34 insertions(+), 15 deletions(-) diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index e03fff99..87616c48 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -172,6 +172,7 @@ jobs: runs-on: ubuntu-latest needs: changes if: needs.changes.outputs.agentex == 'true' + timeout-minutes: 10 steps: - name: Checkout @@ -194,14 +195,14 @@ jobs: - name: Regenerate OpenAPI spec working-directory: ./agentex - run: uv run --with pyyaml python scripts/generate_openapi_spec.py --output openapi.yaml + run: uv run python scripts/generate_openapi_spec.py --output openapi.yaml - name: Verify committed spec matches generated spec working-directory: ./agentex run: | if ! git diff --exit-code openapi.yaml; then echo "❌ The committed openapi.yaml is out of date." - echo "Run 'uv run --with pyyaml python scripts/generate_openapi_spec.py --output openapi.yaml' from agentex/ and commit the result." + echo "Run 'uv run python scripts/generate_openapi_spec.py --output openapi.yaml' from agentex/ and commit the result." exit 1 fi echo "✅ openapi.yaml is up to date" diff --git a/agentex/openapi.yaml b/agentex/openapi.yaml index 69b2745e..aed30cfb 100644 --- a/agentex/openapi.yaml +++ b/agentex/openapi.yaml @@ -209,12 +209,12 @@ paths: schema: $ref: '#/components/schemas/HTTPValidationError' /agents/forward/name/{agent_name}/{path}: - post: + get: tags: - Agents - summary: Forward request to agent by ID - description: Forward a request to an agent by its unique ID. - operationId: forward_request_to_agent_agents_forward_name__agent_name___path__post + 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 @@ -240,12 +240,12 @@ paths: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' - get: + post: tags: - Agents - summary: Forward request to agent by ID - description: Forward a request to an agent by its unique ID. - operationId: forward_request_to_agent_agents_forward_name__agent_name___path__post + 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 diff --git a/agentex/pyproject.toml b/agentex/pyproject.toml index 39a1e00c..2b825c85 100644 --- a/agentex/pyproject.toml +++ b/agentex/pyproject.toml @@ -30,6 +30,7 @@ dependencies = [ "opentelemetry-api>=1.28.0", "opentelemetry-sdk>=1.28.0", "opentelemetry-exporter-otlp>=1.28.0", + "pyyaml>=6.0,<7", ] [dependency-groups] diff --git a/agentex/src/api/routes/agents.py b/agentex/src/api/routes/agents.py index ef33bcea..bfdc53b9 100644 --- a/agentex/src/api/routes/agents.py +++ b/agentex/src/api/routes/agents.py @@ -216,13 +216,30 @@ async def register_agent( raise HTTPException(status_code=400, detail=str(e)) from e -@router.api_route( +@router.get( + "/forward/name/{agent_name}/{path:path}", + summary="Forward GET request to agent by name", + description="Forward a GET request to an agent by its name.", +) +async def forward_get_request_to_agent( + agent_name: str, + path: str, + request: Request, + agent_api_keys_use_case: DAgentAPIKeysUseCase, +): + return await agent_api_keys_use_case.forward_agent_request( + agent_name=agent_name, + path=path, + request=request, + ) + + +@router.post( "/forward/name/{agent_name}/{path:path}", - methods=["GET", "POST"], - summary="Forward request to agent by ID", - description="Forward a request to an agent by its unique ID.", + summary="Forward POST request to agent by name", + description="Forward a POST request to an agent by its name.", ) -async def forward_request_to_agent( +async def forward_post_request_to_agent( agent_name: str, path: str, request: Request, From 6514c8febf3d2af92d35e6c224cb275b95459e60 Mon Sep 17 00:00:00 2001 From: Declan Brady Date: Tue, 5 May 2026 14:25:15 -0400 Subject: [PATCH 3/5] chore: tighten openapi spec generator docstring/comments --- agentex/scripts/generate_openapi_spec.py | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/agentex/scripts/generate_openapi_spec.py b/agentex/scripts/generate_openapi_spec.py index 6fbfe0ed..d76a16b9 100644 --- a/agentex/scripts/generate_openapi_spec.py +++ b/agentex/scripts/generate_openapi_spec.py @@ -1,9 +1,4 @@ -"""Generate the AgentEx OpenAPI spec to a YAML file for Stainless ingestion. - -Imports the FastAPI app and dumps its OpenAPI schema. The lifespan context -(DB / Temporal / Redis startup) is intentionally not run — we only need the -schema produced by route registration and Pydantic models. -""" +"""Dump the FastAPI app's OpenAPI schema to a YAML file.""" from __future__ import annotations @@ -11,8 +6,6 @@ import os from pathlib import Path -# Provide non-empty defaults for env vars consulted at import time so module -# evaluation does not fail in the CI runner where nothing is configured. os.environ.setdefault("ENVIRONMENT", "development") os.environ.setdefault("ALLOWED_ORIGINS", "*") From db8f9fb09b1ed0bcf02d02c55c8e5908dfeb2aa1 Mon Sep 17 00:00:00 2001 From: Declan Brady Date: Tue, 5 May 2026 14:27:34 -0400 Subject: [PATCH 4/5] chore: add make gen-openapi target and pre-commit hook --- .pre-commit-config.yaml | 7 +++++++ agentex/Makefile | 7 +++++++ 2 files changed, 14 insertions(+) diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index a21bd1f0..317d33ee 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -18,3 +18,10 @@ repos: files: ^agentex-ui/.*\.(ts|tsx|js|jsx)$ pass_filenames: true + - id: agentex-openapi-spec + name: Regenerate AgentEx OpenAPI spec + entry: bash -c 'cd agentex && make gen-openapi && git add openapi.yaml' + language: system + files: ^agentex/(src/.*|scripts/generate_openapi_spec\.py)$ + pass_filenames: false + diff --git a/agentex/Makefile b/agentex/Makefile index aff75c28..5727b99c 100644 --- a/agentex/Makefile +++ b/agentex/Makefile @@ -68,6 +68,13 @@ migration: ## Create a new migration (usage: make migration NAME="migration_name apply-migrations: ## Apply database migrations cd database/migrations && alembic upgrade head +# +# OpenAPI Spec +# + +gen-openapi: ## Regenerate openapi.yaml from the FastAPI app + @uv run python scripts/generate_openapi_spec.py --output openapi.yaml + # # Documentation # From 3f76769c28ee30784723ad52de18eb90e347b3a6 Mon Sep 17 00:00:00 2001 From: Declan Brady Date: Tue, 5 May 2026 15:08:17 -0400 Subject: [PATCH 5/5] chore(pre-commit): don't update uv.lock --- agentex/Makefile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/agentex/Makefile b/agentex/Makefile index 5727b99c..8d0171cb 100644 --- a/agentex/Makefile +++ b/agentex/Makefile @@ -73,7 +73,7 @@ apply-migrations: ## Apply database migrations # gen-openapi: ## Regenerate openapi.yaml from the FastAPI app - @uv run python scripts/generate_openapi_spec.py --output openapi.yaml + @uv run --frozen python scripts/generate_openapi_spec.py --output openapi.yaml # # Documentation