# Overview

What agents are and how to manage their lifecycle through the API.



An **agent** is the unit you talk to in Nairi. Each agent runs on Nairi infrastructure and answers prompts via Claude, Codex, OpenCode, or Cursor. Agents are identified by a human-readable slug (the `agent_id`, for example `my-agent`) — that slug is what you pass throughout the rest of the API.

## How it works [#how-it-works]

Agents have two layers:

* **Configuration** — name, description, system prompt, instance count, and attached resources (rules, MCP configs, skills, vaults, env vars). All managed via this API.
* **Deployment** — the actual running agent. Created with `POST /agents/{agent_id}/deploy`, which is asynchronous and returns immediately while the work happens in the background.

## When to use it [#when-to-use-it]

* **Stand up a shared agent for your team in Slack or Discord.** Define its prompt and tools once, attach it to a channel, and let teammates @-mention it from where they already work.
* **Provision a dedicated agent per customer or tenant.** Spin one up at signup, tear it down at churn — no manual dashboard clicks.
* **Roll config changes without restarting containers.** Update the system prompt or swap attached resources, then call `/deploy` with `update_config_only: true`.

## Related [#related]

* [Agent resources](/api/agent-resources/overview) — attach rules, MCP configs, skills, vaults, and integrations to an agent.
* [Env vars](/api/env-vars/overview) — plaintext variables injected into the agent's container.
* [Conversations](/api/conversations/overview) — once an agent is deployed, you drive its work through conversations.