Artemis how-to guides

These task-based guides help you build ABL agents. Each guide starts with the decision or pattern you need, then gives you working ABL to copy into a project. Use the guides alongside the ABL reference. The reference explains what each section and keyword does. The guides show which sections to combine for a scenario, and why.

Prerequisites

Before you use these guides:

Read the ABL overview to understand sections, indentation, and the goal-driven execution model.
Get access to a project where you can create or edit agents.
Identify the tools, workflows, and knowledge bases your agent uses. The examples reference these by name, so you must replace the placeholder names with your own.

Guide categories

Agent architecture and design

Choose an agent pattern, split work across agents, and set execution behavior.

Conversation entry and welcome experience

Control greetings, startup logic, session setup, and channel differences.

Routing and multi-agent orchestration

Route each conversation to the owning agent and debug the routing decision.

Handoff, delegate, escalate, and complete

Transfer control, call sub-agents, escalate to a person, and end a conversation.

Context passing between agents

Pass fields, summaries, history, and memory between agents, and debug missing context.

Data collection and entity gathering

Collect, validate, infer, and protect the values an agent needs from users.

Entities, NLU, and intent understanding

Define entities and intents, normalize user language, handle interruptions, and tune matching.

Agent architecture and design

Decide how many agents to build, how to split their work, and how to configure their execution.

Guide	Use it when
How to choose between a reasoning agent and a FLOW-based agent	You need to decide whether an agent should be goal-driven and flexible, step-driven and predictable, or a mix of both.
How to decide whether to build one agent or multiple specialist agents	One customer-facing experience could be one broad agent or a supervisor with specialists.
How to design a supervisor that routes users to specialist agents	One entry point must identify what the user needs, choose a specialist, and pass enough context.
How to define clear responsibilities for each enterprise agent	An agent is becoming too broad or too vague for builders and support teams to reason about.
How to combine reasoning steps with deterministic FLOW steps	A conversation needs both flexible judgment and predictable execution.
How to write effective agent goals, personas, instructions, and limitations	An agent needs a clear job boundary, a consistent voice, and explicit limits.
How to use behavior profiles to change agent behavior by context	The same agent keeps its core responsibility but must change style, constraints, or tools by context.
How to configure model, timeout, and execution settings for an agent	An agent needs explicit model choice, response limits, timeout boundaries, or concurrency behavior.
How to design reusable agents and modules for large projects	Many agents, tools, and workflows must compose without duplicated responsibilities or routing ambiguity.
How to use EXECUTION.pipeline for agent routing, classification, and short-circuiting	A supervisor needs classifier-assisted routing before the normal reasoning path decides what to do.
How to configure EXECUTION.pipeline models, modes, thresholds, and fallbacks	The execution pipeline exists but needs tuning for model, mode, confidence thresholds, or fallback behavior.

Conversation entry and welcome experience

Control what happens before and during the first user turn: greetings, startup logic, session setup, and channel differences.

Guide	Use it when
How to create a welcome message for a new conversation	A conversation should open with a clear first message before the user asks for help.
How to use ON_START to greet users before the first message	The agent must run startup logic before the user sends the first turn.
How to personalize a welcome message for returning users	The agent should recognize a known user and make the first turn specific to that user.
How to run an authentication or profile lookup during welcome	The first turn should use authenticated context, such as account status or display name.
How to route users from the welcome experience to the right agent	The first assistant turn should guide the user into the right specialist path, or hand off at session start.
How to initialize session variables before the first user turn	Flow steps, routing, templates, or tools need known session values before the user says anything.
How to design channel-specific welcome experiences	Web chat, voice, messaging, or async channels need different startup behavior.
How to handle empty-state and fallback greetings	Startup context may be missing, a branch may not match, or a channel may not deliver proactive content.

Routing and multi-agent orchestration

Send each conversation to the agent that owns the work, handle unclear or bundled requests, and debug the routing decision.

Guide	Use it when
How to route users by detected intent	A supervisor classifies what the user is trying to do, then hands the conversation to the specialist that owns it.
How to design supervisor routing with priority gates	Mandatory checks such as authentication, fraud screening, or consent must run before a business route.
How to route by role, channel, language, and session state	The same user intent must branch by channel, language, role, or current session state.
How to route by tool result, profile lookup, or remembered state	Routing depends on profile, case status, risk, entitlement, or a remembered preference, not just the utterance.
How to route unclear or unsupported requests to a fallback agent	The supervisor cannot confidently choose a specialist, or the request is outside the supported intent catalog.
How to handle messages that contain multiple user intents	Customers bundle several tasks into a single message and secondary requests must not be dropped.
How to clarify before routing to a specialist agent	A request is short, ambiguous, overloaded, or missing the one field that determines ownership.
How to switch the active agent during a conversation	A supervisor should stop answering directly and let a specialist own the next turn.
How to debug routing decisions in traces	You need to explain why a user reached one specialist, or why a route fell through to fallback.

Handoff, delegate, escalate, and complete

Transfer control to another agent, call a sub-agent for a result, escalate to a person, and end the conversation.

Guide	Use it when
When to use HANDOFF instead of DELEGATE	The target agent must talk to the customer or own the conversation, not just return a value.
When to use DELEGATE instead of HANDOFF	The calling agent keeps the conversation and needs a result back from a sub-agent.
When to escalate a conversation to a human	The agent must decide when to stop and pass a conversation to a person.
How to end a conversation with COMPLETE	An agent must finish the conversation, or return control, when its work is done.
How to transfer control to another agent and return later	A specialist does bounded work, then control goes back to the supervisor.
How to transfer control permanently to another agent	The target agent should keep ownership of the conversation after the handoff.
How to call a sub-agent and map its result back	A sub-agent runs a task and the caller needs its output in session variables.
How to run multiple agents in parallel with multi-intent fan-out	Independent requests in one message should run on several agents at the same time.
How to package context for human escalation	A human agent needs the reason, priority, routing, and customer context on arrival.
How to resume after a child agent or human agent completes	You need to know what happens after a child agent or human agent finishes.

Context passing between agents

Control what a target agent receives in a handoff or delegate call, what comes back, and how to find missing context.

Guide	Use it when
How to pass specific fields between agents	A specialist needs values the calling agent already holds, so the customer does not repeat them.
How to pass a conversation summary during handoff	The target agent needs the reason for the handoff, but not the full conversation.
How to pass full, recent, or no conversation history	You must set how many earlier messages a target agent receives.
How to choose the right history strategy for handoff	You must pick between full, last_n, summary_only, auto, and none for a route.
How to minimize context for privacy and compliance	A target agent must receive only the data its job requires.
How to grant another agent access to memory	A target agent must read or update a stored value that the calling agent owns.
How to map child-agent outputs back to parent-agent variables	A child agent collects or computes values that the parent must use afterward.
How to preserve context when calling remote agents	A conversation goes to an agent outside your project over A2A and that agent needs context.
How to debug missing or incorrect context after handoff	A target agent asks for data you passed, ignores context, or receives data you did not intend to send.

Data collection and entity gathering

Collect values from users in a reasoning agent or a FLOW step, validate and infer them, and protect sensitive data.

Guide	Use it when
How to collect information with global GATHER	A reasoning agent must collect several values and the model decides how to ask for them.
How to collect information inside a FLOW step	You need a fixed order of questions in one step before the flow moves on.
How to collect required and optional fields from users	Some fields must be collected and others are welcome but not needed.
How to collect multiple fields across a natural conversation	Customers give several details in one message and the agent must ask only for what is missing.
How to progressively collect fields only when needed	A field applies only after another answer, so customers do not see irrelevant questions.
How to silently extract values without asking the user	The customer may state a value on their own and the agent must capture it without a question.
How to infer values from conversation context	The customer already said a value earlier and a later step must reuse it.
How to confirm inferred values before using them	The customer must approve an inferred value before the agent acts on it.
How to collect sensitive or PII fields safely	A value such as an email, ID fragment, or PIN must stay out of traces, history, and prompts.
How to collect lists, ranges, preferences, and attachments	One scalar is not enough: you need a list, a low and high range, or an uploaded file.

Entities, NLU, and intent understanding

Define the values and intents your agents understand, normalize what customers say, and handle interruptions.

Guide	Use it when
How to define reusable entities for structured extraction	Several fields or agents extract the same kind of value and need one shared definition.
How to use enum entities with synonyms	The customer can name one choice in many ways and the agent must store one canonical value.
How to extract pattern-based values like IDs and phone numbers	A value has a fixed shape and a regular expression must find it in the message.
How to extract dates, numbers, locations, and free text	A field must hold a normalized date, number, amount, place, or note.
How to normalize user language into canonical values	Customers use different words, units, or spellings and the agent must store one value.
How to define intents with examples and keyword patterns	A supervisor must classify what the customer wants and you write the definitions.
How to use scoped sub-intents inside a flow step	A customer may interrupt one step with a small request that the step handles and stays.
How to handle digressions without losing the current flow	A customer interrupts a guided flow and the flow must answer, then carry on.
How to detect multiple intents in one user message	You must understand and tune how the platform decides a message has several requests.
How to improve intent matching with domain glossary and embeddings	Routing sends some requests to the wrong agent and you need to know which settings help.

Get started

Build

Optimize

Deploy

Analyze

References

Prerequisites

Guide categories

Agent architecture and design

Conversation entry and welcome experience

Routing and multi-agent orchestration

Handoff, delegate, escalate, and complete

Context passing between agents

Data collection and entity gathering

Entities, NLU, and intent understanding

Agent architecture and design

Conversation entry and welcome experience

Routing and multi-agent orchestration

Handoff, delegate, escalate, and complete

Context passing between agents

Data collection and entity gathering

Entities, NLU, and intent understanding