Agents
There are two ways to get work out of a colleague. You can hire them — write the job description, decide what they'll have access to, and let a manager sign off. Or you can brief them — hand over a task and let them do it, then read what came back.
The agents area does both, and it keeps them strictly apart. Hiring goes through a review page a
human approves. Briefing runs the agent you already have, for real, on Nirvai's side.
The verbs
| Verb | Scope | What it does |
|---|---|---|
agents.run | run | Briefs the agent. Runs it in Nirvai's cloud and returns its answer plus a real conversation you can open. |
agents.get_run | read | Reads that conversation's transcript back, message by message. |
agents.simulate | run | Reference only. Downloads the agent's definition so your assistant can reason as it. Executes nothing itself. |
agents.describe_schema | — | The grammar for authoring an agent. Documentation only; it changes nothing. |
agents.propose | create | Drafts one or many agents onto a review page. Creates nothing until you confirm. |
agents.create | create | Creates the agent directly, without a review page. |
agents.edit | create | Changes an agent that already exists — merging, never overwriting. |
agents.attach_database | create | Gives the agent a table to read or write. |
agents.attach_knowledge | create | Adds documents or pages the agent can answer from. |
agents.attach_memory | create | Connects a long-term memory store. |
agents.attach_skill | create | Adds a reusable skill the agent can run. |
Listing your agents is nirvai_list_resources(kind="agents"). Reading one is
nirvai_describe(kind="agents", ref=<uuid>) — the agent's manifest: its instructions, its
callable tools and their argument shapes, and pointers to the tables, memory stores, knowledge and
skills it's connected to. Everything downstream starts there, and agents are addressed by that uuid,
never by name.
The manifest names what an agent has; it doesn't inline it. Knowledge files, skill scripts and table rows stay where they are and are fetched only when something actually needs them — so reading an agent stays cheap no matter how much it knows.
Where you finish this
agents.propose hands you a link to /external/agents/…, and that page is not a plain form. It is
the real agent-builder view you already know from Nirvai: capability cards you can open one by
one, and a prominent Create agent button.
- You must be signed in, and only you can open the page — a proposal link is not shareable. Once you've clicked, re-opening it shows Created ✓ and refuses a second copy.
- Channels are not set up there. WhatsApp, Slack, Instagram and the rest are attached to the agent inside Nirvai after it exists.
- To change something, copy the block the page gives you and paste it back into your chat — the page has no way to message your assistant. See the MCP reference.
agents.runuses no review page at all. It returns a link to a real conversation you can open and keep reading.
Running versus simulating
These look similar and are not remotely the same thing.
agents.run | agents.simulate | |
|---|---|---|
| Where the thinking happens | Nirvai's cloud, the agent's real loop | Your assistant's own reasoning, locally |
| Uses the agent's tools & memory | Yes, for real | Only by calling back to Nirvai for each concrete step |
| Leaves a trace | A real conversation you can open | Nothing is executed, nothing is billed |
| Good for | Doing the work | Understanding or rehearsing how the agent would behave |
run is blocking, with a cap of about two minutes. If the agent finishes inside it you get the
answer and a conversation id. If it doesn't, you get a running status and the conversation id
anyway — so get_run can read back whatever completed. There is no background worker that finishes
an overrun for you, so keep a single brief small enough to land.
simulate executes no code of its own. It hands your assistant the agent's definition and its
resolved bindings, and your assistant then plays the part: it adopts the instructions, and for every
concrete step — call a tool, read a table, recall a memory, run a skill script — it calls back into
Nirvai. It is the honest way to answer "what would this agent do?" without spending a run.
Worked examples
Read an agent, brief it, read the reply back. The everyday loop:
# 1. What is this agent, exactly? Never work from memory.
nirvai_describe(kind="agents", ref="a1b2-…")
# → instructions, callable tools + their argument shapes, connected tables, memory, skills
# 2. Brief it. Blocking, capped at ~2 minutes.
nirvai_execute(alias="agents.run",
args={ agent: "a1b2-…", prompt: "Summarize this week's leads and draft 3 follow-ups" },
description="Ask SalesBot for the weekly lead summary")
# → { status: "completed", answer: "…", conversation_uuid: "c9f3-…", session_url: "…" }
# 3. Read the full transcript — or the partial one, if the cap was hit.
nirvai_execute(alias="agents.get_run",
args={ conversation: "c9f3-…", agent: "a1b2-…" },
description="Read back what SalesBot actually said")
Pass the same conversation back into agents.run to continue that chat; omit it to start fresh.
Change an agent without breaking it. Edits merge, so this adds rather than replaces:
nirvai_execute(
alias = "agents.edit",
args = { agent: "a1b2-…",
instructions: "Always cite the source document when answering from the docs.",
tools: ["tools.hubspot_create_contact"] },
description = "Teach SalesBot to cite sources and give it the CRM tool"
)
The new instruction is appended to what's already there, and the tool joins the existing set. To genuinely replace either one, your assistant has to say so explicitly.
Limits & guarantees
- Edits never silently wipe. Instructions are appended, and starters and tools are unioned with what the agent already has. Name, description and behaviour are left alone unless provided. A retried edit doesn't apply twice.
- Attachments are additive and repeatable. Attaching a table, memory store, knowledge source or skill that's already there is skipped, not duplicated.
- Channels do not attach here. Where an agent lives — WhatsApp, Slack, Telegram, Teams, web chat — is set up in the Nirvai app after the agent exists, and there is no verb for it. See Tools & connections.
- Creation is confirmed by a human.
agents.proposestages drafts and returns a review page showing exactly which tools, tables, knowledge and skills the agent will get. Once you confirm, the draft is marked done and cannot be created twice. - No delete. There is no verb to remove an agent over this connection, at any permission level.
- Results are bounded. A run returns its answer plus links; anything large comes back as a handle your assistant can fetch — see What comes back.