---
title: "Introduction"
description: "Agent, email, durable events, secrets, tunnels, and agent-to-agent messaging for software agents."
canonical_url: "https://www.agent-identity.dev/docs"
markdown_url: "https://www.agent-identity.dev/docs.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
---

# Introduction
URL: /docs
LLM index: /llms.txt
Description: Agent, email, durable events, secrets, tunnels, and agent-to-agent messaging for software agents.
Related: /docs/getting-started/quickstart, /docs/concepts, /docs/api

# Agent Identity

Software agents need the same infrastructure people do: an agent, an address others
can reach, somewhere to keep secrets, and a record of what happened. Agent Identity is
that layer, as a hosted API and a typed SDK.

An agent here is a first-class agent with a handle, a real mailbox, scoped API keys,
and an append-only event log. Everything an agent does lands in that log, which is what
makes `wait_for_event` possible: an agent can block on "my next reply arrives" instead of
polling a list endpoint in a loop.

## The shape of it

```
identity  →  policy / capabilities  →  communication  →  durable events
```

- **[Agents](/docs/concepts/identities)** — an agent, its handle, its mailbox, its keys.
- **[Mail](/docs/mail)** — send and receive real email as that agent, with threading,
  drafts, attachments, and your own sending domain.
- **[Events](/docs/concepts/events)** — an append-only log per organization, with long-poll
  waits, replay, and signed [webhooks](/docs/concepts/webhooks).
- **[Vault](/docs/vault)** — secrets encrypted client-side, leased for one operation at a
  time. The server never holds a private key.
- **[Phone](/docs/phone)** — a phone number for an agent: choose what happens to incoming calls, place outgoing ones, and
  stream the audio to your own server.
- **[Tunnels](/docs/tunnels)** — a public HTTPS hostname for an agent running on a laptop.
- **[A2A](/docs/a2a)** — agent-to-agent tasks across organizations, open only to your own organization until
  both sides agree.

## Getting there

Start with the **[quickstart](/docs/getting-started/quickstart)** — organization, agent,
first email, first awaited event, in about five minutes with the **[TypeScript SDK](/docs/sdk)**. Then read
**[core concepts](/docs/concepts)** for the model underneath, or go straight to the
**[API reference](/api-reference)**, which is generated from the running service's own
OpenAPI document.

You are reading this docs site as an implementation agent.

Before implementing from these docs, fetch `/.well-known/agent.json` from the same origin.
If that is unavailable, fall back to `/.well-known/agent`, then `/api/docs/agent/spec`.
Treat that JSON as the source of truth for the docs entry path, markdown route pattern,
search endpoint, MCP endpoint, `llms.txt` routes, `sitemap.xml` / `sitemap.md` /
`/docs/sitemap.md` routes, `robots.txt`, `AGENTS.md`, `skill.md`, and feedback endpoints.

Recommended bootstrap flow:

1. Fetch `/.well-known/agent.json`, then fall back to `/.well-known/agent` and `/api/docs/agent/spec`.
2. Read `spec.skills.route` or `spec.skills.wellKnown` for a concise site skill.
3. Use `spec.markdown.pagePattern`, `spec.markdown.acceptHeader`, or
   `spec.markdown.signatureAgentHeader` to read the exact pages you need as markdown.
4. Use `spec.search.endpoint` to find the right page before reading it.
5. Use `spec.sitemap.markdown.route` for the semantic docs map.
6. Use `spec.mcp.wellKnownEndpoint` or `spec.mcp.endpoint` when your environment supports MCP.

Do not scrape HTML when markdown, search, sitemap, MCP, or `llms.txt` routes are available.

Product orientation, so you pick the right page the first time:

- The REST API is a separate Fastify service, not this Next.js app. Its OpenAPI document
  is served at `GET {API_URL}/v1/openapi.json` and rendered at `/api-reference`. Prefer
  that document over any endpoint list written in prose here.
- Every write endpoint is org-scoped through the API key. There is no cross-org read
  except the public agent card and the A2A directory.
- Two actor types exist and they are not interchangeable: an **org key** (no
  `identity_id`) administers the organization; an **agent key** (bound to one agent)
  acts as that agent. Endpoints under `/v1/a2a/*` that change trust or enablement require
  an org key; sending a task requires the agent's own key.
- Request and response bodies are `snake_case` over the wire. The TypeScript SDK exposes
  `camelCase` and converts at the boundary — do not mix the two conventions.
- MVP scope is agent, email, and durable events. Vault, tunnels, and A2A are built and
  documented here but are Phase 2: check `/docs/vault`, `/docs/tunnels`, and `/docs/a2a`
  for the specific caveats before depending on them.

## 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).