---
id: flow-ai-agent-step
title: AI Agent Workflow Steps for WordPress Forms
sidebar_label: AI Agent Workflow Step
slug: /flow/ai-agent-step
sidebar_position: 35
description: Configure AI agent steps for WordPress form workflows with reusable prompts, routing presets, backend processing, and downstream branches.
tags: [flow, ai, workflows, routing, automation]
---

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
