Submitting tasks

Tasks are the durable A2A record Aly stores in Convex. ASendMessage call currently creates a new task, runs one commerce skill, appends the agent response, and returns the final task state. Use contextId to group related task records from one conversation; do not rely on taskId continuation until the route explicitly supports appending to an existing task.

Authenticated task access

SendMessage can run public skills without auth, but task lookup, listing, cancelation, subscriptions, and push-config management require a workspace-scoped OAuth access token or API key. Browser session JWTs are intentionally rejected on authenticated A2A task routes.

Core methods

`SendMessage`

Create a task from a user message. The request message must include a stable messageId, role, and at least one part. Public JSON uses ProtoJSON camelCase, while snake_case is accepted at the boundary for compatibility.

1curl -X POST https://aly.store/api/a2a \2  -H "Content-Type: application/json" \3  -H "A2A-Version: 1.0" \4  -d '{5    "jsonrpc": "2.0",6    "id": "req_send_1",7    "method": "SendMessage",8    "params": {9      "message": {10        "messageId": "msg_1",11        "contextId": "ctx_4f...11",12        "role": "ROLE_USER",13        "parts": [14          { "text": "Search for hats on store acme." }15        ]16      }17    }18  }'

SendMessage returns result.task. The task contains status, history, artifacts, and metadata.

Structured skill payloads

For deterministic calls, send a structured data part. The intent parser reads fields such as skill, site_slug, cart_token, product_id, quantity, and confirmation_token.

1{2  "jsonrpc": "2.0",3  "id": "req_send_2",4  "method": "SendMessage",5  "params": {6    "message": {7      "messageId": "msg_2",8      "contextId": "ctx_4f...11",9      "role": "ROLE_USER",10      "parts": [11        {12          "mediaType": "application/json",13          "data": {14            "skill": "cart-management",15            "action": "create",16            "site_slug": "acme"17          }18        }19      ]20    }21  }22}

cart-management and checkout requireAuthorization: Bearer ... with write:orders.

`GetTask`

1curl -X POST https://aly.store/api/a2a \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer aly_oauth_..." \4  -d '{5    "jsonrpc": "2.0",6    "id": "req_get_1",7    "method": "GetTask",8    "params": { "taskId": "task_8e3...77c" }9  }'

Returns the task directly in result. A missing or cross-workspace task returns JSON-RPC error -32001. The current route accepts canonical id as well astaskId / task_id, but it does not implement the A2A historyLength request parameter yet.

`CancelTask`

1curl -X POST https://aly.store/api/a2a \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer aly_oauth_..." \4  -d '{5    "jsonrpc": "2.0",6    "id": "req_cancel_1",7    "method": "CancelTask",8    "params": { "taskId": "task_8e3...77c" }9  }'

A cancelable task moves to TASK_STATE_CANCELED. Terminal tasks cannot be canceled and return -32002.

`ListTasks`

1curl -X POST https://aly.store/api/a2a \2  -H "Content-Type: application/json" \3  -H "Authorization: Bearer aly_oauth_..." \4  -d '{5    "jsonrpc": "2.0",6    "id": "req_list_1",7    "method": "ListTasks",8    "params": { "contextId": "ctx_4f...11", "limit": 20 }9  }'

The result is { tasks, nextPageToken, pageSize, totalSize }. The HTTP task-list route also accepts pageSize /pageToken and the older limit /cursor query names. Current filtering is limited tocontextId; A2A status,statusTimestampAfter, historyLength, andincludeArtifacts list parameters are not wired yet.

History returned today

GetTask and ListTasksreturn the task history stored on the Convex task record, bounded by Aly's internal task history cap. They do not currently trim per request.

Streaming

POST /api/a2a/streaming is the direct SSE endpoint. It expects a params envelope rather than a full JSON-RPC request. The JSON-RPC route also supports SendStreamingMessage.

1curl -N -X POST https://aly.store/api/a2a/streaming \2  -H "Content-Type: application/json" \3  -d '{4    "params": {5      "message": {6        "messageId": "msg_stream_1",7        "contextId": "ctx_4f...11",8        "role": "ROLE_USER",9        "parts": [{ "text": "Show products on store acme." }]10      }11    }12  }'

1data: {"statusUpdate":{"taskId":"task_123","contextId":"ctx_4f...11","status":{"state":"TASK_STATE_WORKING","timestamp":"..."}}}2 3data: {"artifactUpdate":{"taskId":"task_123","contextId":"ctx_4f...11","artifact":{"artifactId":"search_results","name":"search_results","parts":[...]}, "lastChunk": true}}4 5data: {"statusUpdate":{"taskId":"task_123","contextId":"ctx_4f...11","status":{"state":"TASK_STATE_COMPLETED","message":{...},"timestamp":"..."}}}

HTTP+JSON routes

Route	Behavior
`POST /api/a2a/message:send`	Accepts the same `{ message, configuration }` params body as `SendMessage` and returns `{ task }`.
`POST /api/a2a/message:stream`	Accepts the same params body and proxies to the SSE streaming handler.
`GET /api/a2a/tasks`	Lists workspace tasks with optional `contextId`, `pageSize`, and `pageToken`.
`GET /api/a2a/tasks/{taskId}`	Fetches one task.
`POST /api/a2a/tasks/{taskId}/cancel`	Cancels one task. `/tasks/{taskId}:cancel` is also wired.
`GET or POST /api/a2a/tasks/{taskId}/subscribe`	Subscribes to a non-terminal task over SSE. `/tasks/{taskId}:subscribe` is also wired.
`GET or POST /api/a2a/tasks/{taskId}/push-configs`	Lists or registers push notification configs. The camel path `pushNotificationConfigs` is also wired.
`GET or DELETE /api/a2a/tasks/{taskId}/push-configs/{configId}`	Reads or deletes one push config by id or URL.

Task context

Use one contextId for a conversation so later listings and operator tools can group related tasks. Aly does not currently dedupe repeated SendMessage calls by message hash, so callers that need retry safety should provide their own idempotency guard.

Push configs

Push configs are stored on the task record. Up to 20 configs can be attached. Delivery URLs must be HTTP(S), with HTTPS required outside localhost development. Terminal tasks cannot accept new push configs, and terminal transitions clear persisted configs.

Errors

JSON-RPC code	Meaning
`-32700`	Parse error.
`-32600`	Invalid JSON-RPC envelope.
`-32601`	Unknown method.
`-32602`	Invalid params.
`-32603`	Internal route or skill error.
`-32000`	Authentication required.
`-32001`	Task or push config not found.
`-32002`	Task not found or cannot be canceled.
`-32003`	Forbidden or push config could not be registered.
`-32004`	Unsupported operation, such as subscribing to a terminal task.

Was this page helpful?