Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.cogniagent.ai/llms.txt

Use this file to discover all available pages before exploring further.

By default, an actor is free-form — it reads its system prompt and decides what to say turn by turn. That’s the right choice 80% of the time. When you need exact control — a specific sequence of questions, a deterministic branch on a condition, a guaranteed handoff after data collection — switch to the step builder. The step builder lives in the Advanced tab of an actor’s config panel.
Step builder Advanced tab with no steps configured

​
Free-form vs scripted

Free-form (default)

The actor talks naturally. The LLM picks what to ask, how to phrase replies, when to use tools. You give it instructions and trust it to act on them.Best for: open-ended conversations, support, qualifying questions.

Scripted (step builder)

The actor follows a strict sequence of steps you define. Each step has a specific behaviour and an explicit next step.Best for: data intake forms, payment flows, identity verification, anything that must complete the same way every time.

​
The step types

A scripted actor flow is built from these step types:
StepWhat it does
Flow StartAuto-created entry marker. You don’t configure it.
Ask QuestionPrompt the user, wait for a reply, extract a value into a slot.
Static MessageSend a fixed, pre-written message. No LLM call.
Act (AI)A single LLM instruction — “summarize what we’ve captured”, “send the confirmation email”.
AI ConditionA true/false branch decided by the LLM based on the conversation state.
SwitchMulti-branch route based on a variable’s value.
Perform ActionInvoke an integration action explicitly.
TransferHand off the conversation to another actor.
EndTerminate the scripted flow. The actor signals done.
Click Add step to insert any of these between the Start marker and the End of your script:
Step builder step types menu

​
Slots — the data backbone

Ask Question steps save their answer to a slot — a session-scoped variable identified by a variableName. Slots are:
  • Visible to every later step in this actor’s flow (via {{variableName}} substitution).
  • Visible to the actor’s system prompt (when Collected information so far is checked).
  • Visible to other actors that the conversation hands off to. Slots survive transfers.
Two ask-question steps with the same variableName share the same slot. By default, if a slot is already filled, the second step is a silent no-op — useful for actors that pick up where another left off.
Ask Question step configuration dialog

​
A worked example — collect details, then send email

The Act step has access to all three slots via {{user_name}}, {{user_email}}, {{user_request}}. Its instruction:
Send a confirmation email to {{user_email}} using the send-email tool. Set the subject to “We received your request” and the body to a short note thanking {{user_name}} and echoing back: {{user_request}}. After the tool call returns, reply to the user in chat saying the email is on its way.
The actor’s Capabilities must include the Gmail send-email action for this to work.

​
Branching with AI Condition

AI Condition evaluates the current conversation state and routes to a true or false branch. The AI Condition step’s prompt is plain language — “Is the user’s issue urgent? Look at the wording, urgency signals, business impact.” — and the LLM returns true or false.
Scripted actor flow with five steps

​
Free-form vs scripted — when to pick which

  • The order in which information comes up is fluid.
  • Users typically wander or change their minds.
  • Most of the value is in the actor responding to what the user says.
  • You’re not sure yet — start with free-form, switch to scripted only when free-form misbehaves.
  • You need every conversation to collect the same fields in roughly the same order.
  • Specific actions (send a calendar invite, charge a card, log a ticket) must happen at specific points.
  • Compliance or audit requires a deterministic trail.
  • You’ve tried free-form and it’s missing fields half the time.

​
Anti-patterns

Building a 20-step script. If your scripted flow is more than ~8 steps, you’re probably modelling something that’s better as multiple actors with routing between them. Smaller actors = easier to debug and edit.
Scripting open-ended conversations. “Help the user figure out which plan they want” is not a script. Use free-form with good instructions instead.

​
Next

Configure an actor

The Basic tab covers free-form actors.

Capabilities

Wire tools that your steps can call.