> ## Documentation Index
> Fetch the complete documentation index at: https://developer.kodexa.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Steps

> Use AGENT steps in Activity Plans to delegate bounded work to a Kodexa agent runtime when workflows require tool use or multi-step reasoning.

`AGENT` steps delegate a bounded part of an Activity to an agent runtime. Use them when the workflow needs tool use or multi-step reasoning, but the Activity Plan should still own the business process boundary.

Agents should help the platform build, inspect, draft, or decide within a well-defined scope. They should not replace the Activity Plan as the workflow model.

## When to Use AGENT

Use an `AGENT` step when the Activity needs an agent to:

* Draft a routine Data Form, schema, or Activity Plan segment for review
* Investigate a document exception using project context and tools
* Assemble test cases for a configured extraction or review workflow
* Compare document evidence against configured business rules
* Produce a structured recommendation that a reviewer or downstream step can use

Use `LLM` for a single bounded prompt. Use `AGENT` when the work involves tools, iterative reasoning, or multiple project resources.

## Basic Shape

```json theme={null}
{
  "slug": "investigate-exception",
  "kind": "AGENT",
  "dependsOn": ["validate:exception"],
  "config": {
    "agentRuntimeId": "runtime-uuid",
    "moduleRefs": [
      "kodexa/invoice-tools",
      "kodexa/vendor-tools"
    ]
  }
}
```

| Config key       | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `agentRuntimeId` | Agent runtime that should run the work                   |
| `moduleRefs`     | Optional modules/tools made available to the agent       |
| `dependsOn`      | Prior Activity steps or actions that must complete first |

The runtime validates that the agent runtime exists and is ready before starting the agent step.

## How It Runs

When the step becomes ready, Kodexa:

1. Resolves the agent runtime.
2. Confirms the runtime is available.
3. Applies runtime concurrency limits.
4. Creates an agent run linked to the Activity step.
5. Supplies project, task, document family, module, and step metadata.
6. Marks the Activity step running until the agent completes or fails.

```mermaid theme={null}
sequenceDiagram
    participant Activity
    participant Step as AGENT step
    participant Runtime as Agent runtime
    participant Tools as Project tools
    Activity->>Step: Dependencies complete
    Step->>Runtime: Start agent run
    Runtime->>Tools: Inspect resources and context
    Tools-->>Runtime: Results
    Runtime-->>Step: Structured outcome
    Step-->>Activity: Continue downstream path
```

## Keep the Boundary Tight

Good agent steps have a tight contract:

* Clear input context
* Clear expected output
* A finite tool set
* A known completion condition
* A downstream consumer for the result

Avoid broad instructions such as "process this packet" or "figure out what to do." Model the business process in the Activity Plan, then use the agent for the part that benefits from agentic help.

## Example: Exception Investigation

```json theme={null}
{
  "slug": "investigate-vendor-mismatch",
  "kind": "AGENT",
  "dependsOn": ["validate-vendor:exception"],
  "config": {
    "agentRuntimeId": "finance-agent-runtime",
    "moduleRefs": ["kodexa/vendor-master-tools"]
  }
}
```

Downstream steps can route the result to review:

```json theme={null}
{
  "slug": "analyst-review",
  "kind": "CREATE_TASK",
  "dependsOn": ["investigate-vendor-mismatch"],
  "config": {
    "taskTemplateRef": "vendor-exception-review"
  }
}
```

The agent gathers context and proposes a resolution. The Task gives a person ownership of the decision.

## Concurrency

Agent runtimes can have concurrency limits. If a runtime is at its limit, the Activity step remains pending until capacity is available. This protects shared runtimes and keeps agent-heavy workflows from overwhelming project resources.

Design with this in mind:

* Put expensive agent steps after cheap deterministic routing.
* Use `SCRIPT` or `LLM` first when they can filter out clean cases.
* Keep agent steps reserved for cases where tool-using reasoning is worth the latency and cost.

## AGENT vs LLM vs SCRIPT

| Need                                             | Use           |
| ------------------------------------------------ | ------------- |
| Deterministic routing or simple transformation   | `SCRIPT`      |
| One prompt with mapped output                    | `LLM`         |
| Tool use, investigation, or multi-step reasoning | `AGENT`       |
| Human ownership of a decision                    | `CREATE_TASK` |

## Outputs

Agent outputs should be structured enough for downstream steps to consume. A useful agent result normally includes:

* A concise recommendation
* Evidence references
* Confidence or risk level
* Missing information
* Suggested next action

If the next step is a human review Task, place the agent result where the Data Form can show it to the reviewer.

## Checklist

* The agent runtime is available to the project.
* The Activity Plan gives the agent a narrow job.
* The agent has only the tools/modules it needs.
* The workflow still has deterministic downstream steps.
* Human review owns final judgment where required.
* Concurrency and latency are acceptable for the business process.

<CardGroup cols={2}>
  <Card title="LLM Steps" icon="message-sparkles" href="/guides/activity-plans/llm-steps">
    Use bounded prompt execution instead of agent delegation.
  </Card>

  <Card title="Create Task Steps" icon="list-check" href="/guides/activity-plans/create-task-steps">
    Hand agent recommendations to human reviewers.
  </Card>
</CardGroup>