---
title: "Core Concepts"
description: "The model underneath — agents, the event log, and how the two fit together."
canonical_url: "https://www.agent-identity.dev/docs/concepts"
markdown_url: "https://www.agent-identity.dev/docs/concepts.md"
last_updated: "2018-10-20"
x_farming_labs_generated_preamble: true
---

# Core Concepts
URL: /docs/concepts
LLM index: /llms.txt
Description: The model underneath — agents, the event log, and how the two fit together.
Related: /docs/concepts/identities, /docs/concepts/events, /docs/concepts/webhooks

# Core Concepts

Four layers, in dependency order. Each one only knows about the ones above it.

**Organization** — the tenancy boundary. Every row in the system belongs to exactly one,
and the API derives it from your key rather than from anything in the request. There is
no cross-organization read outside the deliberately public A2A surfaces.

**[Agent](/docs/concepts/identities)** — a handle, a display name, a
provisioned mailbox, optionally a vault public key, and its own API keys. This is the
thing that acts.

**Capability** — what an agent is allowed to do. Today that is a policy check on send
plus access rules and A2A trust; the interface is shaped for SMS, voice, secret leases,
and tunnel connects, which are not all wired yet.

**[Event](/docs/concepts/events)** — the append-only record of what happened. Every
meaningful state change appends one. Events drive [webhooks](/docs/concepts/webhooks),
`wait_for_event`, and replay.

## Why the event log is the interesting part

An agent that wants to know whether its email got a reply has two options. It can poll a
list endpoint on a timer — burning requests, adding latency equal to half the poll
interval, and getting no help with "did I already handle this one?". Or it can block on
the log.

```ts
const { event, timedOut } = await client.events.wait({
  type: "mail.received",
  filter: { threadId: message.threadId },
  timeoutMs: 55_000,
});
```

The log is durable and ordered, so it is also the answer to what happens when an agent is
offline: nothing is lost, and `since` lets it pick up exactly where it left off.
[Replay](/docs/concepts/events#replay) re-delivers an event to webhook subscribers when a
downstream consumer was broken at the time.

## Naming, on the wire and in the SDK

The HTTP API is `snake_case` — `display_name`, `thread_id`, `timeout_ms`. The TypeScript
SDK is `camelCase` and converts at the boundary. Both refer to the same fields; don't mix
the conventions in one place.

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