sdk-v1

Create Chat Task

Changed on

Create a new SDK-driven task and kick off its first turn.

Single endpoint does three things atomically from the caller's perspective:

  1. Verifies the body's agent_id matches the agent bound to the presented API key. Mismatch -> 404 agent_not_found (404 not 403, so the existence of unrelated agents isn't leaked via error code).
  2. Persists a new :class:Task row owned by the agent's user, with source='sdk' and input set to the user message. Also persists the first user message to task_chat_messages so the existing background execution path can consume it without special-casing this entry point.
  3. Schedules background execution via start_task_in_background (which uses the same coroutine the WebSocket handler does). Returns 202 immediately -- callers poll GET /v1/chat/tasks/{task_id} to observe the eventual completed / failed status.

Args: request: Validated :class:CreateTaskRequest. message.content is guaranteed non-empty by Pydantic; agent_id is the target agent the SDK caller wants to invoke. authed: (Agent, AgentApiKey) tuple resolved by the auth dependency. The agent here is the key-bound agent, the single source of truth for what this caller may touch. db: SQLAlchemy session.

Returns: :class:CreateTaskResponse with the new task_id, agent_id, status='running' (the atomic claim inside the handler flips the row from PENDING to RUNNING before the response is sent), and created_at for the caller to start polling from.

Raises: V1ApiError 401: missing/invalid/revoked key (raised inside get_agent_from_api_key; envelope is uniform with other auth failures). V1ApiError 404: request.agent_id != authed_agent.id. 500 (V1 envelope): any unexpected exception -- the global handler in web/app.py translates to {"error": {"code": "internal_error", ...}} and the raw exception message stays out of the response.

post/v1/chat/tasks

Request

Request body

agent_idinteger required

Target agent's primary key. Must match the agent the presented API key is bound to.

metadataobject nullable

Free-form correlation data the SDK caller can pass through (trace_id, request_id, etc). Not interpreted server-side.

dispatch_class'interactive' | 'batch' nullable

Dispatch class to request for this task: 'interactive' or 'batch'. Omit it or send null to let the server decide. Whether the deployment honors the request is its own setting; the response's 'dispatch_class' shows the class the start command was given.

priorityinteger nullable

Priority of this task's commands, an integer from -10 to 10; higher goes first. Omit it or send null for 0. It takes effect only where the deployment dispatches fairly across accounts, and only orders commands of the same account and the same dispatch class. Messages appended to the task and manual resumes inherit it.

Response

Successful Response

task_idinteger required

Newly created task primary key.

agent_idinteger required

Agent the task is bound to.

statusstring required

Initial status, 'running' in the 202 response (the atomic claim inside POST commits the status flip before the response is sent). Use GET /v1/chat/tasks/{task_id} to observe later transitions.

created_atstring date-time required

UTC creation timestamp.

dispatch_class'interactive' | 'batch' nullable

Dispatch class the start command was given, which is the requested class only when the deployment accepted it. Null when the server runs the task in this process rather than through the dispatch queue. Later commands on the task are not reported here.

Changes

    • info

      added the new optional request property

    • info

      added the new optional request property

    • info

      added the optional property to the response with the status

    • info

      endpoint added