Skip to main content
Choose the smallest structure that meets your targets. Keep language flexible where it helps, and keep rules deterministic where an error matters. Each component you add brings coordination, model calls, context transfer, and new failure paths. Start with one agent. Add a fixed flow, a workflow, or a specialist only when a scenario needs a distinct responsibility or a controlled procedure. Start from the scenarios and targets in Plan an agent journey.

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 ESCALATE triggers as plain sentences. A condition such as intent.category == "human_agent" blocks every escalation when nothing sets it.
See Safety and guardrails and PII protection.

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 in CONSTRAINTS. 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 set EXECUTION: 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.
In ABL, the contract sits in the agent’s 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, and context_access: read stops the call when the value is missing.
  • After the yes, a change to new_flight_id is refused.
  • on_result: set keeps the named values for the reply and later turns, and stops the full result from being stored. Add store_result: true when follow-up questions need the rest.
  • Declare effect: read_only on 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 as result.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
The question names the action and the booking. The flow checks the answer before it asks the eligibility workflow for options. A request to keep the booking, or to do something else, exits without a write.

Use workflow results to choose the path

ABL: route on a workflow result
The workflow applies the fare rules and returns eligibility, fee, and amount fields. The End node maps them under 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
The read-back before this step names the flight, booking, and settlement. The flow then asks for a clear yes. The tool uses 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.
ABL has no source include. Share by structure: a workflow called as a tool, a shared .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.
  1. Change. Make one bounded update, and keep unrelated formatting out of the diff.
  2. Validate and evaluate. Run platform_validate_package and debug_lint_abl, then run the eval sets against the exact candidate.
  3. Review and release. List every route in and every reference with platform_package_model and debug_get_flow_graph. Run focused scenarios, then neighboring routes. Get the owner decisions, release, and verify the active version.
Keep the exported project in Git. Don’t copy a whole agent to make a one-line change: the copies drift, and a later fix reaches only one of them. See Collaborate with Git and Release agents to production.

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
Excerpts on this page explain syntax. They aren’t complete importable agents, so validate the complete file after you change a definition. See the ABL reference.