AI Agent Workflow Step

The ai.agent workflow step is the backend AI action used inside Flow workflows.

It does not directly send the final email or webhook request. Instead, it publishes an ai.agent.requested event into the backend workflow system. The AI backend processes that request and then emits:

• ai.agent.completed
• ai.agent.failed

Downstream workflows can react to those result events, and process-map step-trigger branches can scope those downstream workflows to the exact AI step that emitted them.

Deployment prerequisite

For this step to work in production, Flow backend alone is not sufficient.

You need:

• Flow backend deployed and syncing/running workflows
• AI Kit backend deployed, because its internal AiAgentDispatcherFunction consumes ai.agent.requested and emits ai.agent.completed or ai.agent.failed

If the AI Kit backend dispatcher is not present or not configured correctly, the workflow can publish the AI request event but nothing will process it into a follow-up AI result.

If you expect knowledge-base-grounded answers or classifications, the AI Kit backend also needs a working model configuration and a configured Knowledge Base with ingested content.

What this screen is for

The AI Agent step configuration screen combines four concerns:

1. task intent via Mode
2. optional platform-owned routing via Internal routing
3. prompting via Prompt Text and Additional System Guidance
4. output validation via Response Constraint

If you keep those separate, the configuration is much easier to reason about.

Mode

Mode is the high-level intent passed to the AI backend.

Current values:

• Answer
• Summarize
• Classify
• Extract structured data

Recommended use:

• choose Answer for general generation or response writing
• choose Summarize for concise summaries
• choose Classify for routing and branching decisions
• choose Extract structured data when you need predictable structured output

Mode shapes defaults, but actual behavior still depends on your prompt and schema.

Internal routing

Internal routing controls whether Flow injects a platform-owned routing contract.

Current presets:

• No internal routing
• Route by category
• Route by outcomes
• Draft reply only

Recommended use:

• No internal routing: use when you do not want Flow's routing envelope. This removes the platform routing block, but any custom response schema already present can still remain until you clear or replace it.
• Route by category: use when the AI should choose a stable category such as support, sales, or billing.
• Route by outcomes: use when the AI should return explicit actionable outcomes such as invoke_webhook, invoke_workflow, or send_email.
• Draft reply only: use when the step should produce a structured draft reply and you do not need routing metadata.

Route Keys, Outcome Types, and Signal Keys

When routing is enabled, these fields shape what the AI is allowed to emit.

Route Keys

Use stable category values such as:

• support
• sales
• billing
• crm_lead

These feed process-map branch suggestions like route:support.

Outcome Types

Use reusable action families such as:

• invoke_webhook
• invoke_workflow
• send_email
• set_status

These support branch keys like outcome:invoke_webhook:create_ticket.

Signal Keys

Use optional structured metadata such as:

• priority
• language
• urgency

These support branch keys like signal:priority:high.

Best practice:

• use route for the main business branch
• use outcomes for actionable next steps
• use signals only for auxiliary metadata

Prompt fields

Prompt Text

Prompt Text is the main task instruction and the most important user-authored field.

Good prompts are concrete, operational, and explicit about the decision or artifact you want.

Platform System Block

Platform System Block is automatically injected by Flow when the chosen routing preset requires it.

You do not edit it directly. Its purpose is to enforce the selected routing contract.

Additional System Guidance

Additional System Guidance is your own system-level instruction appended after the platform block.

Use it for tone, policy, or behavior constraints such as:

• be concise
• prefer knowledge base evidence
• avoid speculative claims

Keep the core task itself in Prompt Text.

Response schema

Response Schema Presets

This action generates a starting schema for the current mode or routing preset.

Use Apply routing preset when you want the routing contract schema rebuilt from the current routing configuration.

Response Constraint (JSON schema)

This is the runtime JSON schema contract for the AI output.

When routing is enabled, it should match the routing envelope expected by Flow. In practice that usually means a root object containing routing.route, routing.confidence, routing.reason, and routing.outcomes, with optional routing.signals.

When Draft reply only is enabled, the schema should match the draft reply contract instead.

Important behavior:

• invalid JSON stays in the editor until fixed
• the workflow keeps the draft text instead of silently discarding it

Update Status on Dispatch

Update Status on Dispatch changes submission status immediately after ai.agent.requested is published.

It does not wait for the final AI result.

Use this for visibility transitions such as new -> in-progress, not as a substitute for the final business outcome.

Recommended first setup

For a first downstream-branching workflow, a safe setup is:

• Mode: Classify
• Internal routing: Route by category
• a small set of Route Keys
• optional Signal Keys like priority
• preset-generated routing schema
• concise task-oriented prompt

That gives you predictable process-map branching without forcing a large custom output model from day one.

Common mistakes

• choosing No internal routing and then expecting route-based process-map branching to work
• leaving an older custom schema in place while assuming No internal routing makes the output fully free-form
• using tenant-specific booleans instead of stable route or outcome keys
• treating Update Status on Dispatch as the final AI decision rather than a processing-state transition