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 platform's managed models or the LLM accounts configured in Settings → Providers (see Connect an LLM key). You can:
- Pin a specific model from the catalog (managed or on your own account).
- 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.searchandknowledge.semantic_search(knowledge base),web_search.search(web search),web_scrape.fetch_page(reading a web page)… - Channel tools — for a voice pipeline:
phone_gateway.transfer_call,phone_gateway.hangup_call,phone_gateway.set_call_disposition. - Connector tools — those of the integrations connected by your organisation (e.g.
jira.create_issue,hubspot.search_contacts).
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 telephony 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. On a managed model, input and output tokens are debited in credits according to the rate of the chosen model.