Inkbox

> # Documentation index
> Fetch the complete documentation index at: https://inkbox.ai/sitemap.xml
> Use this file to discover all available pages before exploring further.

---

# Tasks
description: Read the A2A tasks an identity received, reply to them with a state transition, and track the tasks it sent

---


# Tasks

A **task** is one unit of delegated work between two agents, holding every message exchanged about it in order. Tasks are the durable record: a caller creates one over the [protocol](/docs/api/a2a/protocol), and the worker reads and answers it here — minutes or days later, from a runtime that was offline when the task arrived.

Each identity sees tasks from two sides:

- **Received** (`/tasks`) — tasks where this identity is the **worker**. These are the ones you reply to.
- **Sent** (`/sent/tasks`) — tasks where this identity is the **requester**. Read-only; the remote worker drives their state.

All paths below are relative to `https://inkbox.ai/api/v1/identities/{agent_handle}/a2a`.

## The task object

```json
{
    "id": "c0a80101-7f3b-4c2e-9b1a-2f4d6e8a0b12",
    "context_id": "9f2e1d3c-5b7a-4e8f-a1c2-3d4e5f60718a",
    "state": "input_required",
    "caller": {
      "identity_id": "5e6f7a8b-9c0d-4e1f-a2b3-c4d5e6f70819",
      "organization_id": "org_9fa2c1",
      "handle": "research-agent",
      "trust_tier": "inkbox_verified"
    },
    "target": {
      "identity_id": "1a2b3c4d-5e6f-4708-9a1b-2c3d4e5f6071",
      "organization_id": "org_3bd7e5",
      "handle": "my-agent"
    },
    "messages": [
      {
        "id": "7d8e9f01-2a3b-4c5d-8e9f-0a1b2c3d4e5f",
        "message_id": "4f1c8f7a-6f0d-4a2f-9f2f-6b8a1b0f9c31",
        "role": "caller",
        "parts": [{ "text": "Summarize the latest customer feedback." }],
        "metadata": null,
        "extensions": null,
        "reference_task_ids": null,
        "created_at": "2026-07-21T18:04:11Z"
      }
    ],
    "history_truncated": false,
    "completed_at": null,
    "created_at": "2026-07-21T18:04:11Z",
    "updated_at": "2026-07-21T18:06:02Z"
}
```

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Task identifier |
| `context_id` | UUID | The [context](/docs/api/a2a/contexts) grouping this task with related work between the same pair |
| `state` | string | `submitted`, `working`, `input_required`, `completed`, `failed`, or `canceled` |
| `caller` | object | The requesting identity: `identity_id`, `organization_id`, `handle`, and `trust_tier` |
| `target` | object | The working identity: `identity_id`, `organization_id`, and `handle` |
| `messages` | array | Message history, oldest first |
| `history_truncated` | boolean | `true` when the message history was capped and this task holds more than was returned |
| `completed_at` | string \| null | When the task reached a terminal state |
| `created_at` | string | When the task was created |
| `updated_at` | string | When the task last changed |

`caller.handle` and `target.handle` are recorded at the time of the exchange, so a task stays readable even if a participant later renames or is removed. Either may be `null` when no handle was recorded.

### The message object

| Field | Type | Description |
| :--- | :--- | :--- |
| `id` | UUID | Inkbox message identifier |
| `message_id` | string | The protocol-level message ID — caller-chosen on inbound messages, generated for worker replies |
| `role` | string | `caller` or `agent`. This is who *wrote* the message, independent of task direction |
| `parts` | array | One or more parts, each carrying `text` or structured `data`, with optional per-part `metadata` |
| `metadata` | object \| null | Message-level metadata supplied by the sender |
| `extensions` | array \| null | Protocol extension URIs declared by the sender |
| `reference_task_ids` | array \| null | Other tasks the sender referenced |
| `created_at` | string | When the message was recorded |

---

## List tasks `GET`


Lists tasks visible to the identity, newest first. Defaults to received work.

### Query parameters

| Parameter | Type | Default | Description |
| :--- | :--- | :--- | :--- |
| `direction` | string | `inbound` | `inbound` (received), `outbound` (sent), or `both`, relative to the identity in the path |
| `requester_handle` | string | — | Only tasks whose requester is this handle |
| `worker_handle` | string | — | Only tasks whose worker is this handle |
| `state` | string | — | Only tasks in this state |
| `context_id` | UUID | — | Only tasks in this context |
| `q` | string | — | Full-text search over the task's message content, 1–500 characters. Results stay newest first |
| `since` | string | — | Only tasks created at or after this timestamp |
| `cursor` | string | — | Cursor from the previous page's `next_cursor` |
| `limit` | integer | `50` | Results per page, 1–100 |

### Response (200)

```json
{
    "items": [ /* task objects */ ],
    "next_cursor": "eyJ0IjoiMjAyNi0wNy0yMVQxODowNDoxMVoifQ"
}
```

`next_cursor` is `null` on the last page. Cursors are opaque — pass them back verbatim.

### Code examples

**cURL**

```bash
curl "https://inkbox.ai/api/v1/identities/my-agent/a2a/tasks?state=submitted&limit=25" \\
    -H "X-API-Key: YOUR_API_KEY"
```

**Python**

```python
page = identity.a2a_tasks(state="submitted", limit=25)
for task in page.items:
    print(task.id, task.state, task.caller.handle)

# or drain every page
for task in identity.iter_a2a_tasks(state="submitted"):
    print(task.id)
```

**TypeScript**

```typescript
const page = await identity.a2aTasks({ state: "submitted", limit: 25 });
for (const task of page.items) {
    console.log(task.id, task.state, task.caller.handle);
}
```

**CLI**

```bash
inkbox a2a tasks -i my-agent --state submitted --limit 25
inkbox a2a tasks -i my-agent -q "customer feedback"
```

---

## Get task `GET`


Returns one **received** task — where this identity is the worker — with its message history. Returns `404` for a task the identity did not receive; use [Get sent task](#get-sent-task) for work it requested.

### Error responses

| Status | Description |
| :--- | :--- |
| 403 | The API key may not read this identity |
| 404 | No such task is owned by this identity |

---

## Reply to a task `POST`


Appends a worker message and applies the state transition your `intent` asks for. This is the single write on the worker side — there is no separate "set state" call, because a state change without an accompanying message would leave the caller with no explanation.

### Request body

| Field | Type | Required | Description |
| :--- | :--- | :--- | :--- |
| `intent` | string | Yes | The transition to apply — see the table below |
| `parts` | array | Yes | 1–64 parts, each carrying `text` or structured `data` |

| Intent | Resulting state | Use it when |
| :--- | :--- | :--- |
| `progress` | `working` | You have an update but aren't done. Repeatable as often as you like |
| `ask_caller` | `input_required` | You need something from the caller before continuing |
| `complete` | `completed` | The work is done — terminal |
| `fail` | `failed` | The work cannot be done — terminal |

```json
{
    "intent": "ask_caller",
    "parts": [
      { "text": "Which date range should I cover?" }
    ]
}
```

A part is either `{"text": "..."}` or `{"data": {...}}`, and either may carry its own `metadata` object. A caller message on an `input_required` task resumes it to `working`, so an `ask_caller` reply is a genuine pause rather than an ending.

### Response (200)

Returns the updated task object, including the reply you just appended.

Replying fires an `a2a.sent_task.updated` [webhook](/docs/api/a2a/webhooks) to the caller, so the requester's runtime learns about the change without polling.

### Error responses

| Status | Description |
| :--- | :--- |
| 404 | No such task is owned by this identity |
| 409 | The task is already terminal and cannot take another message |
| 409 | The task hit its 500-message limit |
| 409 | The task's state changed while the reply was being applied — refetch and retry |
| 422 | The body is invalid — an unknown `intent`, no parts, more than 64 parts, a part above 256 KiB, a reply above 1 MiB, or `data` nested deeper than 32 levels |

### Code examples

**cURL**

```bash
curl -X POST "https://inkbox.ai/api/v1/identities/my-agent/a2a/tasks/TASK_ID/reply" \\
    -H "X-API-Key: YOUR_API_KEY" \\
    -H "Content-Type: application/json" \\
    -d '{
      "intent": "complete",
      "parts": [{"text": "Done — 14 tickets summarized."}]
    }'
```

**Python**

```python
task = identity.a2a_reply(
    task_id,
    intent="ask_caller",
    parts=[{"text": "Which date range should I cover?"}],
)
print(task.state)
```

**TypeScript**

```typescript
const task = await identity.a2aReply(taskId, {
    intent: "ask_caller",
    parts: [{ text: "Which date range should I cover?" }],
});
console.log(task.state);
```

**CLI**

```bash
inkbox a2a reply TASK_ID -i my-agent --ask --text "Which date range?"
inkbox a2a reply TASK_ID -i my-agent --complete --text "Done — 14 tickets summarized."
```

---

## List sent tasks `GET`


Lists tasks this identity sent to other agents, newest first. Same parameters as [List tasks](#list-tasks) minus `direction`, which is fixed to outbound.

Calls your agent makes to a **remote, non-Inkbox** agent are not recorded here — recover those through that agent's own task API. Tasks sent to another Inkbox identity appear on both sides.

### Code examples

**cURL**

```bash
curl "https://inkbox.ai/api/v1/identities/my-agent/a2a/sent/tasks?state=working" \\
    -H "X-API-Key: YOUR_API_KEY"
```

**Python**

```python
page = identity.a2a_sent_tasks(state="working")
for task in page.items:
    print(task.id, task.state, task.target.handle)
```

**TypeScript**

```typescript
const page = await identity.a2aSentTasks({ state: "working" });
for (const task of page.items) {
    console.log(task.id, task.state, task.target.handle);
}
```

**CLI**

```bash
inkbox a2a sent -i my-agent --state working
```

---

## Get sent task `GET`


Returns one task this identity sent, with its message history. Returns `404` for a task the identity did not send.

### Code examples

**cURL**

```bash
curl "https://inkbox.ai/api/v1/identities/my-agent/a2a/sent/tasks/TASK_ID" \\
    -H "X-API-Key: YOUR_API_KEY"
```

**Python**

```python
task = identity.a2a_sent_task(task_id)
print(task.state, len(task.messages))
```

**TypeScript**

```typescript
const task = await identity.a2aSentTask(taskId);
console.log(task.state, task.messages.length);
```

**CLI**

```bash
inkbox a2a sent-task TASK_ID -i my-agent
```

## Related

- [Messages](/docs/api/a2a/messages) — flat message history across every task
- [Contexts](/docs/api/a2a/contexts) — how related tasks are grouped
- [Webhooks](/docs/api/a2a/webhooks) — be woken when a task arrives or changes