Documentation
How to create a new agent
The agent is the only node that reasons: it reads the conversation, chooses tools and replies. Without tools it can only chat. Here is how to create one and what you configure.
Instructions with history
Every change to the instructions is kept and you can restore a previous version.
Model of your choice
Each agent can use a different model, or the organization's default one.
Test before publishing
Checks flags problems and Try it opens a test chat with the tools visible.
Four ways to start
| Way | Where | Best for |
|---|---|---|
| Chatting with the Builder | Build section | Those who prefer to describe what they want in natural language; the graph is drawn in real time |
| From the visual editor | Graphs → Create node | Those who want to pick and connect nodes by hand |
| From a recipe | Graphs → New graph | Those who want a ready-wired pattern (Telegram assistant, receptionist, team of agents…). See Recipes |
| From an external assistant | Profile → Connect an assistant | Those who develop with Claude, Codex or other tools. See Building with external assistants |
Step by step
- Create the projectIn Graphs choose New graph, empty or from a recipe. A project belongs to a single organization.
- Add the agentCreate node opens a three-step procedure (Choose a node → Kind → Set up). Choose the Agents category.
- Write the instructionsThis is what the model reads: who the agent is, what it knows about your business, how it behaves, when it should ask. Write them in Markdown, with a heading per topic.
- Choose the modelLeave the field empty to use the organization's default model. See LLM models.
- Give it toolsConnect to the Tools port the nodes that offer tools: database, file storage, skill library, connector, MCP server. You connect by dragging from a port or with its +.
- Connect the channelA channel (web app, Telegram, mailbox, voice…) brings conversations to the agent's Conversations port. See Channels.
- Check with ChecksLists the problems that keep the project from running and the "Worth knowing" suggestions, with actions to fix them.
- Try it with Try itOpens a test chat with the agent, with tool calls visible.
- SaveSave applies the new version and rebuilds only the changed nodes; the rest of the project keeps running.
- ObserveFrom first use, Logs shows conversations, tool calls and changes. See Governance and audit.
Writing good instructions
# Role
You are the order-service assistant of a mechanical components company.
## How you speak
Reply in English, briefly and precisely.
## Rules
- Always check the order status with the tool before replying.
- If the customer asks for a change you cannot make, hand the conversation over to a colleague.
## Tools
- `query` to read orders from the database.- Instructions must not promise what no tool allows the agent to do.
- The task goes in the instructions: the one-line description ("What it does") is for people and the model does not read it.
- Long, reusable procedures belong in a skill library rather than in the instructions, because they are only read when needed. See Data and knowledge.
- Every change is kept: the Instructions section shows the history and takes you back to a previous version.
The agent's fields
| Field | Who reads it | What it is for |
|---|---|---|
| Name | People | Name shown in the console |
| What it does, in one line | People and external assistants that reach the agent through an MCP server | Short description; never read by the agent's model |
| instructions | The model | The agent's job, in Markdown |
| Model | The system | An organization model profile; empty = default |
| Who may talk to it | The console | Who can open a chat from the console: organization members (default), a group or everyone. Each channel has its own access control |
Advanced options
| Option | Default | Effect |
|---|---|---|
| Look at images | Off | The agent looks at images on request; requires a model that can see images |
| Listen to audio | Off | Transcribes audio; the transcription service is chosen among ElevenLabs, a Wyoming server or an OpenAI-compatible service |
| Transcribe incoming audio | On | Transcribes message audio before the model reads it (up to 25 MB) |
| Let it split work into subtasks | On | It can hand a piece of work to an empty copy of itself |
| Allow public file links | Off | It can create a public link to a file from the conversation |
| Tool rounds per turn | 64 (maximum 200) | How many tool rounds per turn before stopping |
| Tool timeout | 600 seconds | After this time, the model is told the tool did not respond |
| Model timeout | 600 seconds | Maximum duration, or maximum silence when streaming, of a model call |
Related pages
Bring an agent to production
The path from an agent prototype to a service your colleagues use, with access control, connections to your systems and oversight.
Multiple agents that collaborate
Delegating a task, handing over the conversation, splitting work into subtasks.
Data and knowledge
MySQL databases, file storage and skill library: the persistent state of agents and code.
Recipes: ready-made patterns
Six ready-wired starting projects: Telegram assistant, web app, mailbox, receptionist, agent with code, team of agents.
Have an agent to take to production?Let’s talk.
We show you TeraBrain NX on your case: systems to connect, access and controls.