Skip to main content

Quick Start: Workflow Agent

Who this is for

Developers ready to build an event-driven workflow agent from a sample. If you're still deciding whether this pattern is the right fit, see the workflow overview first.

Get running in 3 steps​

# 1. Clone a maintained sample (e.g., the event-driven claims agent)
git clone https://github.com/awslabs/agentcore-samples.git
cd agentcore-samples/02-use-cases/02-workflow-automation-agents/event-driven-claims-agent

# 2. Install and run locally
agentcore dev

# 3. Send a test event — the agent triages and acts

The Workflow Automation Catalog has maintained samples for incident triage, claims processing, document ingestion, and payment workflows. All include policy gates and non-destructive defaults.

Choose the right sample​

Select the right workflow automation sample for your trigger and action model, understand the safety boundaries, and start building.

Choose this workload when

  • Your agent is triggered by events (EventBridge, SQS, SNS) rather than human chat
  • The workflow involves enriching data, reasoning over it, and taking a discrete action
  • You need idempotent event handling with at-least-once delivery guarantees
  • Actions must be gated by Cedar policies with human-approval checkpoints for high-risk operations

Start with the canonical tutorial

Workflow Automation Agent Catalog

Browse maintained workflow automation agent samples covering event-driven triage, document processing, and multi-step approval pipelines.

Why it fits

Workflow agents follow a Trigger → Enrich → Reason → Act → Emit pattern. The canonical catalog provides maintained samples for incident triage, claims processing, document ingestion, and payment workflows — all with built-in policy gates and non-destructive defaults.

Choose an alternative when

Safety and production boundary

Action risk: Non-destructive triage and ticket creation by default

The default workflow narrative creates tickets and sends notifications — it does not restart services, scale infrastructure, or mutate external state. Alternatives that perform write actions disclose their individual risk profiles and require Cedar policy authorization before execution.

This sample creates a working prototype. It is not production-ready. Before routing real users or production data, complete the Production Readiness checklist.

Central next steps

Event Handling Patterns​

Workflow agents process events from multiple sources. Design your event handler to:

  • Normalize the event envelope — Extract the business payload regardless of whether it arrives via EventBridge, SQS, or direct HTTP invocation. The canonical samples demonstrate payload unwrapping for each source type.
  • Classify before acting — Use the enrichment phase to determine severity, category, and required action before the agent reasons over next steps.
  • Emit structured results — Return machine-readable summaries (ticket IDs, notification confirmations, classification labels) so downstream systems can consume them programmatically.

Idempotency​

Events may be delivered more than once. Protect your workflow with:

  • Deduplication keys — Use a combination of event source, event ID, and timestamp to detect redelivered events. Skip processing if the event was already handled.
  • Idempotent tool design — Tools should produce the same outcome when called multiple times with identical inputs (e.g., "create ticket if not exists" rather than "create ticket").
  • Dead-letter handling — Route events that fail after bounded retries to a dead-letter queue for manual review rather than retrying indefinitely.

Policy Gates and Cedar Authorization​

Cedar policies control which actions an agent can execute and under what conditions. The example below uses the documented Cedar entity types — AgentCore::OAuthUser or IAM principal as the principal, AgentCore::Action::"Gateway___tool_name" for actions, and AgentCore::Gateway::"arn:..." for the resource. This is illustrative; adapt entity types and ARNs to your deployment.

// Allow the triage agent to create escalation tickets
// only when the incident severity warrants escalation
permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"Gateway___create_escalation_ticket",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/incident-gateway"
) when {
  context.input.incident_severity == "HIGH" &&
  context.input.has_enrichment_data == true
};
// Allow notification delivery for MEDIUM or HIGH severity
permit(
  principal is AgentCore::OAuthUser,
  action == AgentCore::Action::"Gateway___notify_oncall",
  resource == AgentCore::Gateway::"arn:aws:bedrock-agentcore:us-east-1:123456789012:gateway/incident-gateway"
) when {
  context.input.incident_severity in ["MEDIUM", "HIGH"]
};

Key policy design principles:

  • Least privilege — Grant only the specific tool actions the agent needs for its workflow stage.
  • Condition-based gating — Use context attributes (severity, time window, enrichment completeness) to restrict when actions fire.
  • Deny by default — If no permit policy matches, the action is denied. Explicitly authorize each tool invocation.
  • Audit trail — Every policy evaluation is logged, providing a complete record of what was allowed and denied.

See Bounded Autonomy for complete Cedar policy patterns.

Human-Approval Patterns​

For actions that cross a risk threshold, require explicit human confirmation before execution:

  • Asynchronous approval — The agent creates an approval request (ticket, Slack message, email) and pauses. A separate event resumes the workflow when approval is granted.
  • Time-bounded approval — Approval requests expire after a configured window. Expired requests route to a fallback path (escalation or cancellation).
  • Approval context — Include the agent's reasoning, enrichment data, and proposed action in the approval request so reviewers have full context.
  • Rejection handling — When approval is denied, the agent records the denial reason and routes to an alternative non-destructive path.

Action Risk Awareness​

Every tool in a workflow agent has a risk profile. Classify tools into tiers:

TierExamplesPolicy Requirement
Read-onlyget_service_health, lookup_account, fetch_documentMinimal — log access for audit
Non-destructive writecreate_ticket, send_notification, add_commentStandard Cedar policy gate
State-mutatingscale_fleet, update_config, modify_permissionsCedar policy + human approval + maintenance window

Default workflows should operate at the non-destructive write tier. Escalate to state-mutating actions only with explicit policy authorization and human-in-the-loop confirmation.

Resource and Cost Awareness​

Workflow agents consume resources proportional to event volume and reasoning complexity:

  • Token consumption — Each event triggers an LLM invocation. Batch low-priority events or implement severity-based routing to control costs.
  • Tool call chains — Complex reasoning may chain multiple tool calls per event. Set maxIterations to bound reasoning depth.
  • Concurrent execution — High event volumes trigger parallel agent executions. Monitor concurrent invocation counts and set concurrency limits appropriate to your downstream tool APIs.
  • Scale-to-zero billing — AgentCore Runtimes scale to zero between events, but log retention and staged assets continue to accrue charges.

What's Next?​

warning

Everything produced by the samples on this page is a prototype until you have applied the controls in Preparing for production. Do not use a prototype endpoint to serve real user traffic.