Skip to main content

Agents

An agent is an automation that talks to a user. The user drives the conversation; the agent decides which tools to use, what to ask, and when the conversation is done. This page covers everything agent-specific.

For the shared concepts (memory, models, knowledge), see Core Concepts. For workflow-specific editing, see Workflows.

When to build an agent (and not a workflow)​

Build an agent when:

  • The user is on the other end of the interaction.
  • You don't know in advance what the user will ask.
  • The interaction takes multiple turns — the user asks, the agent answers, the user follows up, the agent looks something up, and so on.

Build a workflow instead when the order of steps is fixed and there is no user in the loop. See Workflows.

The anatomy of an agent​

Agents share many components with workflows but configure them differently. The big pieces are:

  • Trigger — for agents, the trigger is one of two built-in choices: Chat (the user starts with a free-form message) or Form (the user fills in structured fields first). Both choices appear as cards at the top of the agent editor; you pick one. See Integrations → Chat Input and Form Input for the configuration details.
  • Persona — the agent's identity, expressed as three short fields plus a list of behavior rules. See Persona below.
  • System instruction — the detailed brief for the AI: what tasks the agent can perform, in what order, how to handle edge cases. This is the longest piece of text in the agent definition and the one you will iterate on most.
  • Model — the AI engine the agent uses (see Models).
  • Max iterations — an upper bound on how many internal reasoning steps the agent may take per user turn.
  • Knowledge — optional knowledge bases the agent can search during the conversation (see Knowledge).
  • Output format — optional structured output. By default the agent replies in natural language.

The agent editor: trigger choice (Chat or Form), persona, system instruction, model, and knowledge selection.

The editor​

The agent editor has the same toolbar as the workflow editor — name, description, and the action buttons Jobs, Manual Run, Duplicate, Export, Remove, Save.

The canvas is split into a few sections:

  • Trigger — two cards labeled Chat ("Users start with a free-text message") and Form ("Users fill out a structured form first"). The selected one shows a "Selected" badge. Below the cards, the trigger's own fields appear (welcome message and submit-button label for Chat; form fields for Form).
  • Model — pick the AI model the agent will use.
  • Knowledge — chip selector for the knowledge bases the agent may search.
  • Persona — three fields (role, goal, communication) plus a chip list of behavior rules.
  • System instruction — the long-form brief for the AI.
  • Max iterations — numeric input.
  • Output format — optional. Click Define output format to pick natural language or a JSON schema.

Persona​

The persona is not a single text block. Instead, three short fields shape the agent's identity:

  • Role — who the agent is. "You are an HR onboarder."
  • Goal — what the agent is trying to achieve. "Help new colleagues find answers in their first week."
  • Communication — how the agent speaks. "Friendly, concise, German."

Below the three fields, a chip list lets you add behavior rules — short phrases the agent should follow as guard rails. Typical examples: "understanding untrained staff", "don't decide anything", "in doubt redirect to HR".

You can add a chip by typing into the chip input and pressing Enter. Remove a chip by clicking its × icon.

How the agent decides what to do​

At every turn of the conversation, the agent considers:

  • The full conversation so far.
  • The persona and the system instruction.
  • The list of connected knowledge bases.

It then picks one of three things:

  • Reply to the user with a message.
  • Search a knowledge base and then continue.
  • Mark the conversation as done.

This decision happens inside the AI model. You shape the behavior by writing a clear system instruction, choosing relevant knowledge bases, and tightening the persona fields.

Step by step — build a minimal agent​

  1. Create the automation as Agent (see Create a New Automation).
  2. Pick a trigger — click the Chat or Form card at the top. Chat is the default for "anything could come in"; Form is better when you know the user must provide a fixed set of fields first.
  3. Configure the trigger — for Chat, set a welcome message and the submit-button label; for Form, define the form fields.
  4. Pick a model — for most agents, a mid-sized model is a good starting point.
  5. Fill the persona — role, goal, communication, plus a small list of behavior chips.
  6. Write the system instruction — describe the agent's task in detail. Include examples of what it should and should not do.
  7. Connect knowledge if the agent should know about your documents.
  8. Set max iterations to a sensible upper bound (the default is fine for most cases).
  9. Save.
  10. Manual Run opens a test chat with you as the user. Try the typical questions and the edge cases. Iterate until the behavior is right.
  11. Start the trigger in the Trigger Monitor when you are satisfied. The agent is now available to users from the Inbox.

📷 SCREENSHOT: A Manual Run chat window where the operator tests the agent's behavior.

How an agent decides it is done​

The agent marks the conversation complete when:

  • It has executed the user's request and there is nothing pending.
  • The user explicitly says "thanks, that's it" or similar.
  • The system instruction tells it to stop after a certain milestone.

A completed conversation moves to the Completed filter in the Inbox. Users can still open it to read the transcript, but they cannot continue it. If they want to continue something similar, they start a new conversation.

If you want a hard cap, you can include a sentence in the system instruction like "Always end the conversation after sending the final summary."

Jobs and metrics​

Every conversation produces a job — the same concept as for workflows. The Jobs view lists all conversations as jobs and lets you inspect each one: every message exchanged, every model call, every retrieval, every error. The view is a chronological log.

Agent jobs are kept forever (they are never moved to an archive area). This makes them a permanent record of what happened. It also means a busy agent can accumulate a lot of jobs over time.

Recommendations​

  • ✅ Write the system instruction in plain language and in the first person ("You are…"). Models follow this style well.
  • ✅ Keep the persona fields short — one or two sentences each. Behavior rules belong in the chip list, not as long prose in the role.
  • ✅ Start narrow. An agent that does one thing well beats an agent that does ten things adequately.
  • ✅ Use the Form trigger when the user always has to provide the same fields. It saves the agent from asking for them.
  • ✅ Re-test after changing the system instruction. Small wording changes can have surprisingly big effects on behavior.
  • ⚠️ Watch the agent's token usage in Metrics. Long system instructions cost on every turn.
  • ⚠️ Knowledge access is implicit (the model decides when to search). If the agent should always consult a specific knowledge first, say so explicitly in the system instruction.
  • ❌ Do not put credentials in the persona or system instruction. Use secured fields on the relevant integrations.
  • ❌ Do not connect every available knowledge "just in case". Each unrelated knowledge adds noise and cost on every turn.

What to do next​