Invocation contract

Callers name a workflow, never a model, an agent, or a prompt template. That is the whole contract, and it is what lets the runtime change models or restructure a workflow’s steps without touching any caller.

Request

{
  "actorId": "+61412345678",
  "workflow": "dialler-agent",
  "payload": { "phoneNumber": "+61412345678" }
}
Field Type Required Purpose

workflow

string

yes

A name registered in build_registry(). Unknown names raise KeyError listing the available workflows.

payload

object

yes

Workflow-specific input. Absent or null is treated as {}.

actorId

string

no

Stable per-contact identifier used for AgentCore Memory namespacing. Falls back to the session id when omitted.

The session id is not in the payload — it comes from the AgentCore context object that the platform supplies.

Response

One SSE event:

{
  "session_id": "abc123…",
  "data": {
    "success": true,
    "output": "…final step's text…",
    "structured_output": { "…": "validated Pydantic model from the last step" },
    "stop_reason": "end_turn",
    "usage": { "inputTokens": 4210, "outputTokens": 890 },
    "error": null,
    "steps": [
      { "name": "analyse-history", "output": "…", "structured_output": {…}, "usage": {…}, "error": null },
      { "name": "prepare-brief",   "output": "…", "structured_output": {…}, "usage": {…}, "error": null }
    ]
  }
}

data is a WorkflowResult. On a missing workflow field the entrypoint yields {"error": "workflow is required"} instead.

WorkflowResult field Meaning

success

false when a step failed or payload validation failed

output

The last successful step’s text output; empty string on failure

structured_output

The last step’s validated Pydantic instance, when that step declared an output_schema

stop_reason

end_turn or max_turns

usage

Token totals summed across steps, when the provider reported them

error

Populated when success is false — includes the failing step name

steps

Per-step detail for multi-step workflows

Available workflows

test

Direct passthrough to the dialler agent. Useful for smoke tests and for exercising the agent’s tools interactively.

{ "workflow": "test", "payload": { "prompt": "What is 2 + 2?" } }

Missing payload.prompt returns success: false with "payload.prompt is required for the prompt workflow.".

dialler-agent

Two sequential steps producing a call brief from a phone number.

{ "workflow": "dialler-agent", "payload": { "phoneNumber": "+61412345678" } }
# Step Depends on Output schema

1

analyse-history

—

AnalyseHistoryOutput

2

prepare-brief

analyse-history

PrepareBriefOutput

PrepareBriefOutput is the useful part for a caller:

class PrepareBriefOutput(BaseModel):
    contact_summary: str
    last_discussed: str
    last_interaction_result: str
    recommended_action: Literal["follow-up-call", "email", "sms", "no-action"]
    action_content: str | None    # draft email or SMS body
    call_prompt: str | None       # ready-to-use call script
    urgency: Literal["high", "medium", "low"]

Full schemas: the dialler workflow.

Calling the runtime

AWS CLI

aws bedrock-agentcore invoke-agent-runtime \
  --agent-runtime-arn arn:aws:bedrock-agentcore:us-east-1:625663093496:runtime/agentcore-XXXXXXXX \
  --payload '{"workflow":"dialler-agent","payload":{"phoneNumber":"+61412345678"}}'

The ARN is the AgentRuntimeArn output of the CDK stack:

aws cloudformation describe-stacks --stack-name AgentCoreStack \
  --query "Stacks[0].Outputs[?OutputKey=='AgentRuntimeArn'].OutputValue" --output text

Locally

curl -X POST http://localhost:9000/invocations \
  -H 'Content-Type: application/json' \
  -d '{"workflow":"test","payload":{"prompt":"Say hello."}}'

See Development and container.

Error behaviour

Situation Result

workflow missing

Yields {"error": "workflow is required"}

Unknown workflow name

KeyError from registry.run() listing available names — surfaces as a runtime error, not a WorkflowResult

Required payload field missing

WorkflowResult(success=false, error="…") — validated at the top of the workflow’s run()

A step raised

WorkflowResult(success=false, error='Step "<name>" failed: …'), with steps showing the partial results

A step’s declared dependency did not complete

WorkflowResult(success=false, error='Step "<name>": Missing dependencies: …')

Structured output failed validation

The step still succeeds; structured_output stays None and the raw text is kept in output

The last row is a deliberate choice: a schema mismatch degrades to raw text rather than failing the whole workflow. A caller relying on structured_output must check for None.

Duplicate workflow names

WorkflowRegistry.register() raises ValueError on a duplicate name. Because registration happens at import time, a name collision fails the container at startup rather than serving ambiguous traffic.