Pattern Matrix/White Paper/Action
ADPS Agent Design Pattern White Paper · Module Overview
Action Module · Turn a Decision into a Verifiable External Change
Action Contracts, tool admission, authority and sandboxes, external acceptance, formal patterns, and open questions.
Scope: This page describes the Action subsystem as a whole. The A1–A5 specifications remain authoritative for pattern-level mechanics and verification.
Action begins when an agent is about to change its environment. Sending a message, editing a file, submitting a ticket, running a command, calling a payment API, and operating a GUI are all actions. Unlike drafting text, they leave external state behind, and some effects cannot be undone by producing a better answer on the next turn.
A production action subsystem translates model intent into a contract an external system can inspect: the current step, eligible tools, parameter provenance, approval, execution boundary, acceptance evidence, and recovery position.
Runtime sequence
The sequence can be stated in one line. A reasoning decision enters the Goal Contract and Plan. The Executor selects the current PlanStep. A Prompt Chain produces or validates the step's structured Artifact. The Tool Dispatcher narrows the candidates and decides admission. The Guardrail Sandwich runs PRE, TOOL, and POST. Finally, the business ledger, unified ActionEvent, and checkpoint establish what occurred.
Models may help construct plans, choose tools, and fill parameters. Authorization, idempotency, state freshness, transaction results, and external receipts belong to the runtime and business systems.
Action Contract
An executable action needs at least these fields:
action_id: act_01K2...
goal_ref: goal://payroll/close-2026-08
plan:
version: 7
step_id: verify-approvals
depends_on: [load-batch]
intent:
operation: payroll.verify_approvals
tool:
name: approval_service.read_batch
registry_version: 12
inputs:
batch_id:
value: batch_8842
source: state://payroll/current_batch
authority:
risk: read_only
approval: none
execution:
sandbox: payroll-readonly-v3
idempotency_key: act_01K2
verification:
expected: all_required_approvals_present
evidence: receipt://approval-service/check-901
recovery:
checkpoint: checkpoint://run-8842/step-4
The contract brings natural-language intent, plan position, tool version, parameter provenance, authority, execution environment, acceptance evidence, and recovery position into one record. Without these elements, a successful tool call can be mistaken for a successful business outcome.
ReAct or an explicit plan
The action module does not require a full plan for every task. The choice depends on task length, side effects, environmental change, and recovery requirements.
| Condition | Direct ReAct | Explicit Plan |
|---|---|---|
| Steps | Few; the next step follows from the current result | Many; dependencies, parallel work, or phase constraints exist |
| Side effects | Read-only or easy to reverse | Writes, releases, payments, or other consequential actions |
| Environment | Exploratory and tolerant of trial and error | Production with stable process and audit requirements |
| Recovery | Restarting is acceptable | Work must resume from confirmed progress |
| Acceptance | Visible after each step | Stage artifacts, approvals, and final regression are required |
A long-task Plan should be a versioned artifact rather than hidden in conversation history. Its stable core includes a step identifier, dependencies, expected artifact, acceptance condition, eligible tools, and recovery position. Domain DSLs can add business verbs and constraints without attempting to cover every industry in one language.
Interface priority
Structured interfaces usually take precedence over GUI operation:
- Domain APIs, Skills, and certified commands provide explicit parameters, permissions, and receipts for stable workflows.
- Controlled CLI execution fits development, operations, and batch work, but requires command, directory, resource, and network policies.
- GUI operation reaches capabilities without a published interface and therefore needs reproducible state, screenshots, or other inspectable evidence.
GUI is not an inferior capability. Its state and outcome are simply harder to establish, and interface drift is more frequent. Use a stable structured interface where one exists. When GUI is the only path, make recognition, interaction, waiting, and acceptance explicit in the contract.
How the five specifications divide the work
| Pattern | Responsibility | Boundary |
|---|---|---|
| A1 Tool Dispatch | Determine eligible tools and select the current action | The registry must express authority, risk, freshness, concurrency, and provenance |
| A2 Plan-and-Execute | Preserve dependencies, artifacts, approvals, and recovery positions in long tasks | A Plan may be revised locally; committed actions cannot be silently rewritten |
| A3 Prompt Chaining | Connect linear stages through structured artifacts and programmatic gates | A downstream stage should not rely only on a free-form summary from the previous stage |
| A4 Guardrail Sandwich | Admit before execution, isolate during execution, and verify afterward | POST cannot pretend to undo an effect; compensation and human takeover require explicit design |
| A5 Minimal Tool Set | Narrow the visible tool surface by responsibility, step, and risk | Rare capabilities need on-demand discovery; necessary tools cannot be removed to satisfy an arbitrary count |
A1 through A4 are core patterns. A5 remains an extension. A2 uses orchestration and A3 uses a chain. They can be nested, but a multi-step plan does not make their topology identical.
Events and execution topology
The action workshop examined whether event-driven execution should become a seventh topology. The current catalog remains unchanged:
- Events define when an action is triggered and how it is delivered, delayed, and replayed.
- Execution topology defines how control unfolds after the task starts.
- Choreography describes local-rule and event-based coordination without a central orchestrator.
A system may begin with an event, route to a tool, orchestrate a plan, and run a loop inside one step. The event bus does not assign one topology to the entire workflow.
Sandboxes, gates, and evidence
Commands, filesystem writes, network access, and external APIs need bounded execution. A sandbox answers where execution can technically reach. Approval answers whether this action is authorized. Tool policy defines the allowed class of action. ActionEvent records what actually happened.
Before execution, check identity, authorization, parameter provenance, target state, idempotency, and risk. Afterward, check the result schema, business invariants, observed side effects, and external receipt. An exit code of zero or HTTP 200 does not establish business completion.
In 2026, these controls are increasingly exposed as runtime contracts. OpenAI's account of running Codex safely combines sandboxes, approval policy, network rules, and agent-native telemetry. The OpenAI Agents SDK exposes tool schemas, tool guardrails, human intervention, and tracing. Claude Managed Agents tool configuration can disable individual capabilities or require confirmation. These interfaces move action control out of prompt convention and into enforceable runtime policy.
Three production failures
The tool is correct but the state is stale. Refresh critical state before a write and include the observed version in the write condition. Correct dispatch against an old state still produces the wrong change.
The step completes but the goal does not. A tool receipt proves that a call ended. Stage artifacts, a business ledger, and external acceptance determine task completion.
Recovery repeats a side effect. A checkpoint that records only the step number is insufficient. Every irreversible action needs an idempotency key, external receipt, and committed marker. Recovery checks the facts before deciding whether to replay.
Open questions
- Which PlanStep fields can remain stable across domains, and which belong in domain DSLs?
- How can replay data establish a threshold for moving from ReAct to an explicit Plan?
- What common form should GUI evidence, authorization, and failure receipts take?
- How should one Action trace connect model intent, tool admission, sandbox events, and the business ledger?
- What cross-industry failure evidence is needed to stabilize the boundary between event-driven mechanisms and C6 Choreography?
Workshop record
This overview draws on the A1–A5 specifications and the first ADPS Action workshop, held on 6 August 2026. Bingsheng Ru chaired the discussion. Core participants included Qingfeng Li, Dong Zhang, Jun Luo, Hongshan Tang, Wei Wang, Pylon Peng, and Leida Ren.
Read the workshop record · All workshops · White Paper contributors