ARG Standard

Appearance

Using ARG for action capable agents ​

ARG: Action space & offline graph evolution

0 Objective of this guide ​

Audience ​

This guide is written for:

  • product builders designing agents that must take real actions
  • platform and infrastructure teams integrating agents into production systems
  • agent engineers who need predictable, auditable behavior

It assumes you already understand basic agent concepts and want a production safe way to let agents act.

What you are building ​

You are building an agent that can perform actions, not just answer questions.

Those actions are not free form. They are executed through a structured Action Space governed by:

  • policy constraints
  • taxonomy validity
  • deterministic routing rules

Online behavior stays deterministic. The agent never invents new actions or structure at request time. Policy always comes first. Taxonomy coherence is enforced before any action decision.

This design is what allows ARG agents to act safely in production.

What you will be able to do by the end ​

After reading this guide you will know how to:

  • map concrete tools and workflows to explicit Action nodes
  • route incoming requests using policy first and taxonomy safe classification
  • execute actions under budgets, permission checks, and safety checkpoints
  • emit ARG ActionWrites that can be reused by the offline evolution loop

The goal is not just execution. The goal is execution that improves the system over time without breaking determinism.

Out of scope ​

This guide does not re explain the full protocol. Those details already exist and are referenced when needed.

Specifically out of scope

It also does not cover deep design of general taxonomies outside the action domain.

1 Essential concepts ​

1.1 Action capable agents in ARG ​

ARG makes a hard separation between what happens online and what evolves offline.

Online hot path:

  • the reasoning graph is treated as fixed during a request
  • no nodes, edges, labels, or clusters are created or modified
  • the agent may execute actions and write episodic logs
  • this guarantees low latency, determinism, and auditability

This online contract is defined in:

Offline evolution loop:

  • logs and outcomes are analyzed after the fact
  • new Action nodes, edges, or refinements are proposed
  • changes are applied only through lifecycle rules and versioning

Offline refinement mechanics are defined in:

1.2 Action primitives ​

To reason about actions safely, ARG uses explicit primitives.

ActionType:

  • a top level intent family
  • used early to decide whether a request belongs to an action domain
  • helps separate Action, Info, and Memory behavior

Labels:

Action node:

  • a structured, executable unit in the graph
  • binds an intent to a concrete workflow or toolchain
  • includes constraints, preconditions, and execution semantics
  • routing and traversal rules are defined in

Cold start domain agent:

Outcomes and constraints

  • every action runs under explicit budgets
  • permissions and role checks are mandatory
  • safety checkpoints prevent unsafe execution paths

ARG ActionWrite:

  • an episodic operational record emitted after execution
  • captures what was attempted, under which constraints, and with what outcome
  • never mutates the active graph online
  • later consumed by the offline consolidation loop in

1.3 Vectors are approximators ​

In ARG, vectors are used to make routing fast and scalable. They are never allowed to make authoritative decisions.

Vectors help with

  • early intent detection during initial classification:
  • shortlisting candidate labels or Action nodes
  • local retrieval of execution context once routing is already constrained

Vectors never decide:

  • authorization or permission
  • whether an action should be executed
  • creation or modification of nodes labels or edges

The vector layer is an accelerator. It narrows the space of choice. It never defines truth or safety.

The exact boundaries of vector usage inside taxonomy arbitration are defined in:

Policy gates that override any vector signal are defined in

Concrete examples ​

Bad pattern
An embedding is close to SendEmail so the agent sends an email.

What is missing

Bad pattern
An embedding is close to DeleteUser so the agent executes.

What is missing:

Correct pattern:

2 Action pipeline overview ​

This section summarizes how an action request flows through ARG. Each step corresponds to a specific contract in the protocol.

2.1 Online request time loop ​

1 Policy pre check
The request is validated for scope safety and permissions before any routing. This step can block refocus or constrain the request.
See ARG Core Step 1 Policy Pre-Check

2 Context Weaver
The request is classified into an ActionType and a taxonomy coherent label set. Invalid or incoherent labels are rejected.
See ARG Core Step 3 Context Weaver

3 Binding
Based on validated labels and constraints the system decides between

  • an existing structured Action node:
  • a cold start domain agent
  • a clarify instead of act path

Traversal contracts are defined in
ARG Core Step 7 Traversal

4 Execute under constraints and log
Execution enforces:

  • budgets
  • permissions
  • safety checkpoints

Execution semantics are defined in
ARG Core Step 8 Action

5 Emit an ARG ActionWrite
Each action attempt produces an episodic operational record. These records are immutable during the request.
See ARG Core Step 10 MemoryWrite

2.2 Offline consolidation and graph evolution loop ​

Offline processing improves the Action Space without affecting online determinism.

1 Aggregate episodes and extract patterns
ActionWrites and outcomes are clustered to detect:

  • missing Action nodes
  • unsafe ambiguity
  • overbroad routing

Aggregation inputs are defined in
ARG Core Offline Loop

2 Taxonomy guided candidates
Proposed nodes labels and edges are checked for taxonomy plausibility. The Weaver qualifies but does not decide structure.
See Context Weaver Offline Role

3 Scoring policy and risk checks plus lifecycle
Replay based scoring separates strong from weak signals. Policy and security violations are penalized. Lifecycle rules gate publication.
See ARG Core Offline Scoring

4 Publish to the ARG Core
Approved changes are versioned and released. The online graph remains fixed during requests.
See ARG Core Lifecycle

3 Conceptual prerequisites ​

3.1 Define the action scope ​

Define what the agent can do. Make the boundary explicit and enforce it consistently.

Include:

  • domain boundaries
  • forbidden categories
  • refocus behavior when the request is out of scope

Scope enforcement lives in the Policy Manager kernel:

Online scope gating is part of the request envelope:

3.2 Define the Action taxonomy ​

The Action taxonomy is the stable backbone of routing. It must be strict enough to prevent unsafe routing and flexible enough to evolve offline.

Define:

  • label naming conventions
  • granularity rules that avoid micro actions that drift
  • coherence rules for parent and child relationships
  • synonym and exclusion rules that prevent overlap collisions

Taxonomy coherence and validation are enforced by the Weaver:

Taxonomy evolution must be offline and child label first:

3.3 Define Policy Manager governance ​

Policy is the authorization layer. It does not route the domain. It constrains and authorizes what routing is allowed to do.

Define:

  • decisions:
    • ALLOW
    • ALLOW_WITH_REFOCUS
    • RESTRICT
    • BLOCK
  • multi role governance using RBAC and ABAC
  • budgets:
    • time
    • tool calls
    • cost caps
  • refusal and clarify rules when constraints prevent safe action

Policy outputs and constraints are defined here:

4 Build the Action Space ​

4.1 Action node model ​

An Action node is an executable contract. It is the unit that turns a label routed intent into a bounded workflow.

Include in every Action node:

  • intent and description for humans and for machine routing
  • ActionType and attached labels
  • preconditions and validations:
    • checklist style
  • parameter schema:
    • input
    • output
  • constraints:
    • permissions
    • budgets
    • safe defaults
  • executor binding:
    • workflow id
    • toolchain
    • handler
  • observability requirements:
    • events
    • metrics
    • traces

Execution time behavior for Action nodes is defined in:

4.2 Action graph structure ​

The Action graph should make routing predictable and safe. Prefer patterns that keep ambiguity local and prevent unsafe shortcuts.

Common edge patterns:

  • parent and child
  • similar intent
  • prerequisite
  • follow up

Recommended structural patterns:

  • intent hierarchies that match label hierarchies
  • domain hubs with strict edge types and strict budgets
  • progressive rollout using versioning and compatibility rules

Traversal behavior and guardrails are defined in:

4.3 Action node lifecycle ​

Define a lifecycle for Action nodes:

  • DRAFT
  • ACTIVE
  • DEPRECATED
  • REMOVED

Define promotion criteria:

  • strong success rate
  • low risk profile
  • stable parameters over time

Define rollback policy:

  • fast deprecation on regressions
  • alias and redirect rules when structure changes

Offline lifecycle and versioning mechanics are defined in:

5 Online routing decisions ​

5.1 Policy pre check gates ​

Policy is the first hard gate. It can stop refocus or constrain the request before any routing.

Policy pre check covers:

  • scope
  • safety and content rules
  • permissions
  • budget constraints

See:

5.2 Context Weaver outputs for Action routing ​

The Weaver produces taxonomy coherent labels and confidence. It separates candidate narrowing from deterministic validation.

Key behaviors:

  • fast path in most requests
  • escalation path only when ambiguity persists
  • strict validator as the final arbiter

Expected outputs:

  • ActionType aligned intent family
  • L_final label set
  • confidence_global
  • flags that explain uncertainty and missing coverage

See:

5.3 Binding to an existing Action node ​

Binding is selecting the executable target among valid candidates.

Core rules:

  • match labels to nodes through node label attachments
  • apply policy constraints before scoring
  • score within a bounded neighborhood
  • select top candidates using thresholds and tie breakers
  • policy constraints first when breaking ties

See:

5.4 Fallback to a cold start domain agent ​

Cold start is used when no Action node exists or coverage is missing. It must be bounded and must not invent structure online.

When to use it:

  • no suitable Action node exists
  • coverage gap is detected
  • risk remains low enough to proceed under strict constraints

How to bound it:

  • allowed tools
  • allowed labels
  • strict budgets
  • full audit logs

Cold start safety rules apply when ambiguity remains. Prefer clarify or info first over direct action on high risk intents.

See:

5.5 Clarify instead of act ​

Clarify is the third explicit branch. It is triggered when acting would be unsafe or underspecified.

Common triggers:

  • low score or low margin
  • RESTRICT constraints block candidate actions
  • missing required parameters for an Action node
  • conflicting labels or unstable taxonomy region

Clarification rules:

  • ask minimal questions
  • keep it safe and scope aligned
  • avoid presenting high risk actions as defaults

See:

5.5 Clarify instead of act ​

Clarify is the third explicit branch. It triggers when acting would be unsafe or underspecified.

Trigger conditions:

How to phrase clarification:

See:

6 Execution synchronization ​

This section explains how an agent runtime executes an Action node contract without breaking the online determinism rule.

6.1 Pattern A Structured Action workflow ​

Preconditions:

Execution:

Outcome capture:

6.2 Pattern B Cold start domain agent ​

Cold start is allowed only when no dedicated Action node exists. It remains a bounded planning path.

Bounded local planning:

Sandboxing:

Hard rule:

See:

6.3 Idempotence retries and transactions ​

Idempotence:

  • use stable deduplication keys to prevent double send or double charge
  • record the idempotence key in the ActionWrite for audit and replay

Retries:

  • default to safe retries only
  • never retry actions that are not idempotent unless the tool provides transactional guarantees
  • respect budgets as hard stops

Transactions:

  • when the domain supports compensation or rollback, treat it as a first class Action node pattern
  • log both the forward action and the compensation attempt

6.4 Secrets and tool permissions ​

Secrets separation:

  • keep credentials out of prompts and out of Action node chunks
  • use scoped credentials per tool and per tenant

Controlled escalation:

Tool permission enforcement:

7 ARG ActionWrites ​

ActionWrites are governed episodic logs. They capture operational truth without mutating the online graph.

Recommended wording:

  • ARG ActionWrite
  • ARG MemoryWrite Action

7.1 Recommended ActionWrite schema ​

Required fields:

Why this schema matters:

7.2 Memory guard and PII ​

Memory protection:

Retention and minimization:

  • keep only what is needed for audit and offline refinement
  • separate audit trails from user facing memory

Write path governance:

7.3 Operational observability ​

Track at minimum:

Dashboards and alerting:

Offline consumption:

This section matches the offline half of Figure 1. Online execution produces ActionWrites. Offline consolidation turns those episodes into controlled graph improvements.

8.1 Episode aggregation ​

Aggregate ActionWrites into stable groups before proposing any structural change.

Group by:

Detect coverage gaps:

  • frequent no node bindings
  • repeated cold start executions
  • high clarify rates in a specific label region

Aggregation inputs and logging requirements are defined in:

Extract stable patterns:

  • recurring parameter sets
  • recurring context signatures
  • recurring prerequisites and safety checkpoints
  • failure modes tied to a specific node or label set

8.2 Taxonomy guided candidates ​

Offline candidate generation must remain taxonomy guided. The Weaver qualifies taxonomy plausibility but does not decide structure.

Candidate types:

  • new Action nodes for recurring intents
  • refinements of labels and edges
  • splits and merges when nodes are too broad or too granular

Candidate generation is defined in:

Weaver offline role:

Taxonomy maintenance chain:

8.3 Scoring policy checks and publishing ​

Each candidate must be scored with strong and weak evidence separation. Action success is treated as a strong system signal.

Replay and scoring:

  • replay based evaluation when possible
  • penalties for complexity and safety risk
  • separation of strong signals from weak signals
  • ARG Core offline scoring

Validation and publishing gates:

Policy and risk checks:

Lifecycle and versioning:

  • promotion to ACTIVE
  • staged deprecation and removal
  • alias tables when needed
  • ARG Core lifecycle

Publish to ARG Core:

9 End to end examples ​

Each example maps to one branch in Figure 1. Each includes inputs outputs decisions thresholds logs and common errors.

9.1 Existing Action node already exists ​

Flow:

9.2 Cold start domain agent no node exists ​

Flow:

9.3 Clarify instead of act ​

Flow:

10 Production checklist and anti patterns ​

10.1 Go live checklist ​

Routing:

Budgets and timeouts:

Idempotence:

  • idempotence keys for all side effect actions
  • safe retries only

Audit and redaction:

Rollback plan:

Testing:

10.2 Anti patterns ​

Never do these.

Create or modify nodes online:

Let vector similarity authorize an action:

Execute without preconditions:

Over fragment Action nodes and destabilize taxonomy:

Log too much or log without governance:

11 Annexes ​

This section is implementation facing. It provides stable contracts and reference material.

11.1 JSON contracts ​

Contracts:

11.2 Standard flags ​

Uncertainty and safety flags:

11.3 Errors and codes ​

Action execution errors:

11.4 Runtime synchronization patterns ​

Patterns:

  • runtime to Action node execution contract
  • idempotence and deduplication keys
  • transactional compensation when available
  • bounded cold start execution rules

11.5 Related guides ​

See also:

  • retrieval agents guide
  • long term memory guide
  • other domain specific agent patterns

Released under the Apache License 2.0

ARG v1.1 Specification