# Agents

An **Agent** on Wire is a registered third-party integration that authenticates and operates on containers. Agents are the primitive your SDK speaks through, your dashboard registers, and your audit trail attributes actions to.

This page defines what an Agent is and how it fits alongside Containers.

## Definition

An Agent is a record in Wire that represents the thing acting on a container. Not a person, not a one-off API key, but a named integration with its own identity, credentials, and lifecycle.

When you register an agent, you get:

- A stable `agentId` (your slug) that identifies the integration across reconnects, deployments, and versions
- A credential pair the SDK uses on every request
- An audit identity. Every `wire_*` call is attributed to the agent, separate from any user that authorized it
- A lifecycle independent of any individual user's session

Three properties follow from this:

1. **Revocation is scoped to the agent.** If your integration has a security incident, revoke the agent's credentials. User accounts and other agents are untouched.
2. **Tool access is scoped per credential.** Give one agent the full `wire_*` surface, give another `wire_search` only. The credential carries the tool allowlist.
3. **Audit attribution is end-to-end.** Every action is logged with the agent as the actor, distinct from the user underneath. Useful when the same user has connected multiple agents to the same container.

## How agents authenticate

An agent acts on behalf of the end-user. Your user has a Wire account. They authorize your agent against their account through a browser-based consent flow. Your agent then operates on their containers with a scoped credential.

You do not store user data. You do not manage their containers. You do not bill them. Wire owns the consent screen, the OAuth handshake, and the connection lifecycle. Your agent keeps speaking MCP, now with whatever context the user has brought along.

**Use cases:**

- An AI coding assistant that connects to a developer's personal Wire memory container
- A research tool that operates on whatever containers the user has set up
- A Claude Code plugin that talks to the user's wire-memory container

See the [Wire SDK guide](/build/sdk/) for the connect flow, install, and the Connection result you hand to your agent's MCP client.

## Agents and Containers

Agents and Containers are different primitives, and the distinction is load-bearing.

- **Containers** are where context lives. Files, entries, tools, an MCP endpoint. The unit of stored context.
- **Agents** are who acts on context. A registered identity that authenticates, operates within a permission scope, and is attributed in audit.

An agent connects *to* containers. It does not contain context itself. The container belongs to the end-user's organization; your agent is granted scoped access to it.

## Permissions and audit

Every agent action is recorded at the container level. Wire's audit log captures:

- Which agent (`agentId`) made the call
- Which container was operated on
- Which tool was invoked (`wire_search`, `wire_write`, and so on)
- When the call happened
- What was returned (digested for read-heavy results, full for writes and deletes)

Audit trails are visible to the container's owner. The end-user sees what your agent did on their behalf, separate from anything they did themselves and separate from what other agents did to the same container.

Tool-level scoping lives on the credential, not the agent record. The same agent can have one credential with full access for production and a second credential with `wire_search` only for read-only integrations. Revoking either credential leaves the other untouched.

## Naming and identity

The agent's `agentId` is a stable slug you choose at registration. It is the identifier the SDK passes on every call, and the identifier shown in audit entries. Pick something descriptive and short. The slug does not change for the life of the agent.

The package name `@wire/sdk` is shared across all agents.

## Next steps

- **Building an agent**: start with the [Wire SDK guide](/build/sdk/).
- **Understanding how agents fit alongside the rest of Wire**: read [Core Concepts](/getting-started/concepts/).
- **Authenticating from an MCP client**: see the [MCP Authentication guide](/mcp/authentication/).