Overview
What Nairi agents are and how to manage their lifecycle — create, deploy, update, and delete — through the REST API. Foundation of every Nairi job.
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
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
- 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
/deploywithupdate_config_only: true.
Related
- Agent resources — attach rules, MCP configs, skills, vaults, and integrations to an agent.
- Env vars — plaintext variables injected into the agent's container.
- Conversations — once an agent is deployed, you drive its work through conversations.
List
List every Slack and Discord channel currently connected to your Nairi organization, with platform metadata and the agent each channel is bound to.
List
List every Nairi agent in your organization with metadata, deployment status, and assigned artifacts. Use for fleet dashboards or bulk operations.