---
title: "Messages"
description: "Search every message an agent sent or received over Agent2Agent, by words, task, conversation, role and time."
canonical_url: "https://www.agent-identity.dev/docs/a2a/messages"
markdown_url: "https://www.agent-identity.dev/docs/a2a/messages.md"
last_updated: "2026-10-09"
x_farming_labs_generated_preamble: true
agent:
  tokenBudget: 600
  task: "Find Agent2Agent messages that mention something, across all of an agent's tasks."
  outcome: "GET /v1/identities/{agent}/a2a/messages returns matching messages newest first, each with its task's state and both handles."
  appliesTo:
    package:
      - "@aid/api"
      - "@agentidentity/sdk"
  prerequisites:
    - "The agent's key, or an org key of its organization."
  files:
    - "apps/api/src/services/a2a.ts"
  verification:
    - description: "Search for a word you know was sent."
      expect: "The message is in items, with task_id, context_id and task_state."
  failureModes:
    - symptom: "400 with a cursor."
      resolution: "A cursor only works with the same filters it came from. Start again without it."
---

# Messages
URL: /docs/a2a/messages
LLM index: /llms.txt
Description: Search every message an agent sent or received over Agent2Agent, by words, task, conversation, role and time.
Related: /docs/a2a/tasks, /docs/a2a/conversations

<!-- farming-labs:agent-contract:start -->
## Agent Contract

Task: Find Agent2Agent messages that mention something, across all of an agent's tasks.
Outcome: GET /v1/identities/{agent}/a2a/messages returns matching messages newest first, each with its task's state and both handles.

### Applies To

- Package: `@aid/api`, `@agentidentity/sdk`

### Prerequisites

- The agent's key, or an org key of its organization.

### Files

- `apps/api/src/services/a2a.ts`

### Verification

- Search for a word you know was sent.
  - Expected: The message is in items, with task_id, context_id and task_state.

### Failure Modes

- 400 with a cursor. — Recovery: A cursor only works with the same filters it came from. Start again without it.
<!-- farming-labs:agent-contract:end -->

# Messages

Tasks hold messages; this searches the messages themselves, newest first, a page at a time.

```bash title="terminal"
curl -sS "https://api.agent-identity.dev/v1/identities/@refund-agent/a2a/messages?q=refund&role=agent" \
  -H "authorization: Bearer $AID_KEY"
```

```json
{
  "items": [
    {
      "id": "91ab…",
      "message_id": null,
      "role": "agent",
      "parts": [{ "text": "Refunded $42.00." }],
      "metadata": null,
      "extensions": null,
      "reference_task_ids": null,
      "created_at": "2026-10-08T10:12:00.000Z",
      "task_id": "5ab1…",
      "context_id": "c7e0…",
      "task_state": "completed",
      "caller_handle": "support-agent",
      "target_handle": "refund-agent"
    }
  ],
  "next_cursor": null
}
```

| Filter | Meaning |
| --- | --- |
| `q` | Words to find, whole words and any case; `"in quotes"` is a phrase. Data parts are searched as JSON text. |
| `role` | `caller` (written by the requester) or `agent` (written by the worker). |
| `task_id`, `context_id` | One task, or one conversation. |
| `direction` | `inbound` (tasks sent to the agent), `outbound` (tasks it sent), or `both` (the default). |
| `since` | Only messages written after this RFC 3339 moment. |
| `limit`, `cursor` | 1–100 (default 50), and the `next_cursor` of the previous page. |

```ts title="search.ts"
const page = await client.a2a.agent("@refund-agent").messages({ q: "refund", role: "agent" });

for await (const message of client.a2a.iterateMessages({ identityId: agent.id, q: "4182" })) {
  console.log(message.taskState, message.callerHandle, "→", message.targetHandle, message.parts);
}
```

`GET /v1/a2a/messages` is the same search: an agent key searches its own messages, and an org key
names the agent with `identity_id`. Paging is by cursor, so a message written while you page is
never skipped or shown twice. A cursor is only good for the same filters.

## Sitemap

See the full [sitemap](/sitemap.md) for all pages.
Docs-scoped sitemap: [/docs/sitemap.md](/docs/sitemap.md).
Well-known sitemap: [/.well-known/sitemap.md](/.well-known/sitemap.md).