Choose a reasoning, scripted, or hybrid agent
Ask whether the model chooses the next action, or whether the conversation must follow a fixed sequence. A flow is part of an agent’s design. It doesn’t create a separate agent.
In a hybrid design, keep eligibility checks, required confirmations, and writes deterministic. Use reasoning in the stages that benefit from interpretation. See the how-to guides Choose a reasoning agent or a flow and Combine reasoning and flow steps.
Choose an agent or a workflow
Use an agent to manage a conversation. Use a workflow to run a repeatable backend process. An agent can call a workflow as a tool when it needs both.
Use a single tool for one bounded operation. Put a multi-step process in a workflow when it needs deterministic branching, consistent state handling, or an explicit result contract.
Other building blocks
See the how-to guide Choose a single agent or specialists.
Sections of an ABL agent
An ABL agent file is easier to review when each section answers one question. The Designer groups fields into Identity, Coordination, Behavior, Capabilities, and Lifecycle tabs. Those tabs don’t map one-to-one to ABL sections, so use the Editor to inspect the source as a whole.
Keep agent names, route descriptions, and tool descriptions consistent. A user request needs one clear owner. If two specialists can accept the same request, their descriptions state the boundary in both directions.
Guard safety and money routes with a value that only a tool sets. Every Voyager route into booking data needs
identity_verified == true, and only verify_traveller writes it. With the Reasoning Pipeline on, intent descriptions act as routing rules.
An agent gets hard to manage when its purpose is vague, its prompts repeat each other, or its tool schemas diverge. Split stable, reusable instructions from scenario-specific rules. Give shared tools and behavior profiles an owner. Keep a change history that says what changed, why, and which cases proved it.
Put each rule where it is enforced
A Prompts library change doesn’t update an agent that is already deployed. Build and release the matching agent version, then verify it in a new session.
Enforce confirmations in the tool. Don’t rely on “ask before changing” in prose alone. Set
confirm: always on the write tool, or read back in a FLOW step and set confirm: never on the tool. Confirm in one place, or the user hears the question twice. The workflow behind the tool still checks eligibility and the row version.Safety, guardrails, and secrets
Give each risk the control that checks it.
Check these defaults before release:
- A guardrail lets text through when its provider fails. Set Closed (block on error) for compliance checks.
- The guardrail Escalate action stops the text. It doesn’t transfer the conversation.
- New projects start with every built-in PII pattern off. Turn on the ones your journeys need.
- Write
ESCALATEtriggers as plain sentences. A condition such asintent.category == "human_agent"blocks every escalation when nothing sets it.
Credentials and tokens
Guardrail rules and streaming safety
A guardrail check sees one item: a message, a reply, tool arguments, a tool result, or a handoff. It never sees the history. Put rules about collected values inCONSTRAINTS.
In ABL, a rule without kind checks output, and a rule without action only warns. Set both on every rule. Order checks by cost: a CEL Expression needs no model call, a Provider rule makes one classifier call, and each LLM Check makes one model call.
Output guardrails can hold a reply until it is complete. Set the mode in Project → Settings → Runtime Config → Streaming Safety.
When an Agent Table fits
Use Agent Tables for typed, durable rows that an agent or workflow queries and reuses, such as service cases, orders, customer preferences, or an operational queue. First confirm the feature is on for the workspace and project. Choose the scope by who needs the data.
Use memory for a single remembered value, a lookup table for fixed extraction choices, and a knowledge base for document search. Give each table tool only the operations it needs. An empty operation set is read only.
Scopes describe data visibility, not environment isolation. Writes through the public Tools API can reach the same production rows from development or staging. Use approved synthetic data. Studio debug and eval sessions use isolated overlays.
Choose models
Register provider connections and models in the workspace catalog first (Admin → AI Configuration → Models). Then select project models in Project → Settings → Models. An agent can setEXECUTION: model, but the effective choice follows the active model-access mode. Enforced access requires the model to be selected for the project. Compatibility mode uses its configured resolution order. Check the effective model and its source before you compare evals.
Change one model setting per eval run, and test each change in a new conversation. See AI configuration.
Design tool contracts
A tool contract says what the tool does, which inputs it needs, and what effect it has. It also says what the model must not supply, what needs a confirmation, and which result fields the agent can use. Keep credentials outside the agent definition, and reference an auth profile by name.- Read tools return only the fields the agent uses.
- Write tools validate current state, reject stale or unauthorized actions, and use idempotency, so a repeated request doesn’t create a second effect.
- When several operations must succeed or fail together, put them in a workflow that checks prerequisites and returns a clear outcome.
- Keep calculations and business rules out of free-form model reasoning.
TOOLS section. Shortened from Disruption:
ABL: tool contract
- The confirmation question is “Shall I” plus the first sentence of the tool’s description: “Shall I rebook this trip for VY318-2026-10-21?” Start that sentence with a short verb phrase.
- The model never sees or types
booking_ref. The runtime fills it from the session, andcontext_access: readstops the call when the value is missing. - After the yes, a change to
new_flight_idis refused. on_result: setkeeps the named values for the reply and later turns, and stops the full result from being stored. Addstore_result: truewhen follow-up questions need the rest.- Declare
effect: read_onlyon every read tool. A workflow or MCP tool with no effect counts as a write, so it waits while another action waits for a confirmation.
Tool contract settings
A normal business outcome, such as “not eligible”, can reach an End node and complete without an error. The agent sees only the fields mapped under
output. A success: false value exists only if the workflow maps it. A failed, cancelled, or rejected workflow run raises a tool error, which the agent’s ON_ERROR handler can handle. Branch on the mapped result for ordinary refusals, and use ON_ERROR for execution failures.
See Tools in the ABL reference.
Workflow tool settings
Register a workflow as a tool at Project → Resources → Tools → Workflows → Register Workflow. The start node’s inputs become the tool’s parameters, and the agent reads the End node’s mapping asresult.output.<field>.
See Workflows.
Example: a cancellation flow
This example places questions, checks, and writes in an explicit order. A fixed flow fits when policy requires the same steps every time. Ordinary questions can still go to an agent that is better suited to them. The outcome: explain the allowed refund or credit, confirm the exact booking and choice, cancel once, and read back the result. Eligibility and amounts come from workflows, not model arithmetic.Ask for a specific decision
ABL: scripted flow step
Use workflow results to choose the path
ABL: route on a workflow result
output, so the agent reads quote.output.refund_amount, and templates use the values for the exact quote.
Give every gather step a way out. Use
DIGRESSIONS for an in-scope side question, then return to the question. Route a refusal to an explicit no-change step. Bound repeated attempts with MAX_ATTEMPTS and ON_EXHAUSTED.
Ask once, then perform the write
ABL: confirmation and write
confirm: never because the flow already asks, so the user doesn’t hear a second confirmation. The workflow still validates its inputs and handles an already-cancelled booking without repeating the action.
If the write outcome is unknown, don’t retry blindly. Read the workflow run and the booking state first.
Prove the important paths
The flow controls the conversation order. The workflow controls whether the action is allowed.
Keep a large project manageable
- Keep a one-page map for each substantial agent: purpose, routes in, tools, data, flow, handoff, tests, owner, and known limits. Have a coding assistant build it from
platform_package_model, keep it in Git next to the ABL, and regenerate it in the same change as the agent. - Split an agent when its responsibilities have distinct tools, rules, or ownership, and evaluation shows the split helps.
- Don’t create one agent per utterance, or put a thin supervisor in front of a single specialist.
- Prefer one routing level, unless a deeper route has a clear cost and a testable purpose.
- Before you split, tighten instructions, move fixed order into a
FLOW, and cut tools. A split adds a routing step to every turn that crosses it. A long flow is cheap; long instructions and many tools aren’t. - Review the routing map when you add a journey, so neighboring routes stay distinct.
.tools.abl file, one behavior profile attached with USE BEHAVIOR_PROFILE, or a config variable. A Prompts library entry is a complete system prompt, not a shared fragment. Each agent repeats a shared tool’s signature and description word for word, or the compiler warns W721. See the how-to guide Design reusable agent modules.
Project map worksheet
Fill this in from sources you can access. Keep it short, and link to authoritative files or records. Mark unknown fields as unknown. Don’t fill gaps with plausible guesses.Lifecycle of an agent change
Agent Platform keeps three stages apart: the working copy you edit, a version you publish, and a deployment that runs a version in an environment. Editing the working copy changes only Studio test chats, working-copy eval runs, and any channel bound to None. Record the version and environment whenever you diagnose behavior.- Change. Make one bounded update, and keep unrelated formatting out of the diff.
- Validate and evaluate. Run
platform_validate_packageanddebug_lint_abl, then run the eval sets against the exact candidate. - Review and release. List every route in and every reference with
platform_package_modelanddebug_get_flow_graph. Run focused scenarios, then neighboring routes. Get the owner decisions, release, and verify the active version.
ABL at a glance
ABL agent files use uppercase section names. Start with purpose and behavior, then add only the capabilities the journey needs.ABL: tool and check