AI Agents
The agent node invokes a LLM with a composed context and a set of tools. It is the central AI building block of betool.
The role / mission / selection triad
An agent does not know on its own what to do. Three things drive it:
- Role — how it works (style, constraints, posture). Short. Reusable across agents.
- Mission — what it must do for this specific use case. Longer. Pipeline-specific.
- Selection — which context data it receives as input. Composed explicitly.
An agent that misbehaves almost always has a role, mission, or selection problem — not a model problem. Before upgrading the model, check these three first.
Configuring the selection
The selection determines exactly what the LLM sees. Five types:
| Type | Effect |
|---|---|
key | Reads ctx.results[<key>] — e.g. exchange.intent |
prefix | Concatenates all keys under a prefix — e.g. project.* |
literal | Raw text with placeholders — e.g. "Question: {user_message}" |
file | Attaches a file (multimodal) — e.g. webhook.payload._files |
history | Includes the N previous turns (native multi-turn) |
The first four compose the user_message for the current turn. history is an orthogonal channel passed in the LLM messages[] array.
No runtime fallback. If the selection is empty, the LLM receives "" and logs a warning. You must explicitly include whatever the agent needs — there is no magic.
LLM model
Chosen from the models configured in Administration → Models. You can:
- Pin a specific model (e.g.
claude-opus-4-7). - Use the organisation's default model.
- Define a fallback (if the primary fails, switch to a secondary).
Tools
Tools are the functions the LLM can call. You select them from the catalogue:
- Global tools —
knowledge.search,web.fetch,compute.now… - Channel tools — for a voice pipeline:
voice.barge_in,voice.hangup,voice.transfer… - Domain tools — created by your operators (e.g.
crm.create_ticketexposed via an operator node).
An agent only sees the tools that are genuinely reachable within its execution context. An agent in an email pipeline will not be offered a voice tool.
Output format
Three options:
- Free text — for user-facing responses.
- Structured JSON — the agent must produce JSON that conforms to a defined schema (strictly validated).
- Tool call only — the agent writes nothing: it either calls a tool or does nothing.
JSON mode is mandatory for agents whose output feeds into a downstream condition or another agent.
Best practices
- Describe tools precisely. The description the LLM sees must cover: WHAT, WHEN TO USE, WHEN TO AVOID, FORMAT. A description that is too short means the LLM guesses — which means invisible bugs.
- Test with a benchmark. See Benchmarks.
- Keep the mission consistent. A mission that changes across 3 versions means a regressing agent. Version your missions.
Costs
See Pricing. With BYOK, you pay your LLM provider directly. Otherwise, expect approximately 30 credits per 1K input tokens and 90 per 1K output tokens.