Pattern A: Agent as Workflow Step

The agent operates as one step within a larger deterministic workflow. The workflow handles sequencing, data flow, and branching. The agent handles the reasoning-intensive step.

flowchart LR S1["Step 1: Metadata Extraction<br/>(deterministic)"] --> S2["Step 2: ReAct Agent<br/>(reasoning)"] S2 --> S3["Step 3: PbotApproval<br/>(human review)"] S3 --> S4["Step 4: Custom Table<br/>(log results)"] style S2 fill:#f3e8ff,stroke:#9333ea

When to Use

  • Most of the process is deterministic, but one step requires judgment
  • You want the workflow to control overall flow while delegating reasoning to the agent
  • The agent is a specialist embedded in a structured pipeline
  • You need predictable sequencing before and after the reasoning step

Complete Example: Claim Packet Review

A workflow that extracts structured metadata from a claim packet, asks an agent to review the packet and supporting evidence, then routes the recommendation to a human approver.

json
{
  "name": "claim_packet_review",
  "definition": {
    "actions": [
      {
        "type": "extract_claim_metadata",
        "properties": {
          "document_ref": "doc:doc_claim_packet"
        }
      },
      {
        "type": "loop",
        "filter": {
          "condition": { "eq": ["@claim_metadata.review_required", true] }
        },
        "properties": {
          "mode": "react",
          "objective": "Review this claim packet and decide whether it should be approved, rejected, or escalated. Use the available tools before you answer.\n\nClaim packet:\ndoc:doc_claim_packet",
          "tools": [
            { "type": "action", "name": "lookup_policy" },
            { "type": "action", "name": "check_prior_claims" },
            { "type": "action", "name": "draft_claim_response" }
          ],
          "max_iterations": 8,
          "on_stuck": { "iterations": 3, "action": "escalate" },
          "result_key": "claim_recommendation",
          "include_trace": true
        }
      },
      {
        "type": "PbotApproval",
        "filter": {
          "condition": { "eq": ["@claim_metadata.review_required", true] }
        },
        "properties": {
          "comment": "Review the recommendation for claim {{claim_metadata.claim_id}}",
          "request_payload": {
            "claim_id": "@claim_metadata.claim_id",
            "policy_id": "@claim_metadata.policy_id",
            "recommendation": "@claim_recommendation.answer",
            "confidence": "@claim_recommendation.confidence"
          }
        }
      },
      {
        "type": "custom-table",
        "properties": {
          "table": "claim_review_log",
          "operation": "write",
          "keys": ["run_id"],
          "values": ["@__run_id"],
          "fields": {
            "claim_id": "@claim_metadata.claim_id",
            "review_required": "@claim_metadata.review_required",
            "recommendation": "@claim_recommendation.answer",
            "approved": "@__approved",
            "reviewed_at": "@now"
          }
        }
      }
    ]
  }
}

How It Works

  1. Metadata extraction (deterministic) ā€” a registered action reads the packet and writes structured fields into workflow context
  2. ReAct loop (agent) ā€” the embedded agent reviews the packet, calls the allowed tools, and writes a recommendation into @claim_recommendation
  3. PbotApproval (human) ā€” a reviewer sees the recommendation and decides whether to accept it
  4. Custom Table (deterministic) ā€” the workflow records the outcome for later audit and reporting

The workflow still controls the pipeline. The agent runs inside one bounded step. It cannot skip the approval step or mutate steps that follow it.

Key Properties

  • doc: references in the objective ā€” the runtime resolves document references before the agent sees the prompt, so the agent can reason over packet text without unsupported {{...}} interpolation
  • filter on the agent step ā€” the agent only runs when the extracted metadata says review is required
  • on_stuck: escalate ā€” if the agent cannot reach a grounded answer, it pauses for human input instead of silently guessing
  • result_key: "claim_recommendation" ā€” the final answer is written back into workflow context for downstream approval and logging

Need one agent run per item in a large batch? Use separate workflow runs or child workflows. Nested loop steps are not supported in the current workflow definition format.

ā†’ Next: [Pattern B: Agent as Trigger](/agents/deployment-patterns/agent-as-trigger)