Skip to main content

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 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

{
  "slug": "investigate-exception",
  "kind": "AGENT",
  "dependsOn": ["validate:exception"],
  "config": {
    "agentRuntimeId": "runtime-uuid",
    "moduleRefs": [
      "kodexa/invoice-tools",
      "kodexa/vendor-tools"
    ]
  }
}
Config keyDescription
agentRuntimeIdAgent runtime that should run the work
moduleRefsOptional modules/tools made available to the agent
dependsOnPrior 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.

​
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

{
  "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: 
{
  "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

NeedUse
Deterministic routing or simple transformationSCRIPT
One prompt with mapped outputLLM
Tool use, investigation, or multi-step reasoningAGENT
Human ownership of a decisionCREATE_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.

LLM Steps

Use bounded prompt execution instead of agent delegation.

Create Task Steps

Hand agent recommendations to human reviewers.