AI Agents — Technical Reference
This page describes how Nirvai agents work beneath the chat interface, in technical terms, for developers and technically-inclined users. It focuses on observable behavior and the model agents follow, rather than implementation internals.
Architecture model
An agent is a configuration over a shared runtime: its identity and instructions, the tools it can call, its knowledge base, its skills, and any connected database tables.
- Agents are streaming-first — output is sent to the client as it is produced, token by token.
- Each conversation runs in an isolated session with its own working directory, memory, and code-execution environment. Sessions never share state.
How an agent acts — the execution loop
An agent does not pick a single function and stop. It reasons, then acts by running a short program that calls its tools, observes the output, and repeats until the task is done. (This code-execution approach is sometimes called CodeAct.)
- Each turn runs a bounded number of steps (a safety cap) before it must stop.
- The code environment is reset every turn — nothing held in program variables persists between turns. Carrying information forward is done through memory (below).
- Running code, rather than one function call at a time, lets an agent chain several tool calls, use loops and conditionals, and process data within a single step.
Tools
Tools are presented to the agent as callable functions. They come in several categories:
| Category | What it is |
|---|---|
| Native | Built-in capabilities: web search, document reading, image vision/generation, file storage, dates |
| Custom | User-created integrations with third-party REST APIs |
| Connector | Pre-built integrations (calendar, email, spreadsheets, chat apps, and more) |
| Database | Per-table actions on connected database tables (scoped by permission) |
| Knowledge | Search and read across the agent's knowledge base |
| Skill | Reusable processes the agent loads and runs (see below) |
| Channel | Send actions specific to the channel the agent runs on |
- Tool-output tiering: small results are returned inline; large results are summarized into a compact data card (shape + sample) and exposed as a variable; very large results are additionally saved to a file. This keeps big outputs from overflowing the working context.
- Shared 25-tool limit: an agent's custom tools and database tools share a single budget of 25. A read database connection counts as 2 tools, write as 5, full as 7; each custom tool counts as 1.
Memory
Because the code environment resets each turn, persistent memory is the only way to carry information forward. It has three typed slots, all shown to the agent at the start of every turn:
| Slot | Holds |
|---|---|
plan | The session roadmap — objective, approach, and progress |
context | A reading list — file paths to re-read next turn (not cached content) |
state | Workflow variables — IDs, names, choices, the current step |
- Each slot holds one value that is overwritten on update.
- Conversation history is kept to a recent window; older turns drop off.
- Memory is for compact notes — not large data or file contents, which are re-fetched each turn.
Knowledge
- Knowledge (files and URLs) is processed at creation time: text is extracted, summarized, and keyworded, and an index is stored.
- At runtime the agent searches that index by keyword and reads the matching sources on demand.
- Simpler agents use keyword search; deep-knowledge agents use a graph-based search for more connected retrieval.
- Knowledge is for retrieval — material the agent searches when answering. Step-by-step process documentation the agent should follow belongs in a skill instead.
Skills
A skill is a folder: a SKILL.md interface document plus optional Python scripts, reference docs, and data files.
- Skills are loaded on demand and run inside the same code environment;
SKILL.mddocuments exactly how to use them. - Scripts use pre-installed libraries (no installs at runtime), return JSON-serializable results, and save files as relative paths.
- Skills come from three places: built-in platform skills, official community templates you can install, and skills you create yourself.
Channels & platforms
The same agent logic runs across the web app and external channels (WhatsApp, Instagram, Messenger, Telegram, Slack, Discord, Teams). Channel-specific output rules and send actions are swapped in per channel.
On external channels, the interface can't block new input while the agent is working. To avoid corrupting a conversation, execution is serialized per session: one message runs at a time, and messages that arrive mid-run are queued and processed when the current run finishes.
Agent types
- New agents are created as one of two types: Simple (instructions + general knowledge) or Simple with Knowledge (adds a searchable knowledge base). The type is set automatically based on whether you add knowledge.
- The runtime also powers specialized internal agent variants (research, workflow, document assistants, and more), but those aren't part of the standard creation flow.
Limits & guarantees
- Each turn is capped at a bounded number of steps.
- Oversized tool output is truncated to a preview and saved to a file the agent can open.
- Each conversation is isolated — one channel never sees another channel's session.
- Usage is metered as credits per execution.
What's next
- Skills — package reusable processes for your agent
- Connect databases — give your agent permission-scoped table access
- Tasks & Automations — run agents on records and in multi-step flows