Agent State

sec0-sdk/agent-state provides the primitives for propagating agent state across hops in the Sec0 runtime. It ensures state is predictable, header-safe, and supports opt-in analytics for intent-vs-execution deviation tracking.

Runtime Contextual Agent Governance

In a multi-hop agentic system, a single user request can traverse an orchestrator, multiple agents, tool servers, and external APIs. Each hop needs context about who initiated the request, what the objective is, and what happened at previous hops to make governance decisions. Sec0 solves this by encoding runtime context into a canonical agent state payload that flows with every call. At each hop, the agent state carries:

Context	Purpose	Governance Use
`nodeId`	Identifies which agent/hop is executing	Resolves agent-scoped policy for this node
`runId`	Links all hops in a single request graph	Correlates audit trail across distributed hops
`variables`	Scoped key-value pairs per hop type	Compliance rules can inspect objective, plan, and execution state
`metadata`	Arbitrary data attached by each hop	Enriches audit envelopes with model, temperature, etc.
`parentRef`	Reference to the parent hop	Reconstructs the hop graph for deviation analysis

This means the middleware can enforce contextual governance: a compliance rule can evaluate not just the tool input/output, but also the agent’s stated objective, the orchestrator’s plan, and the full chain of prior hops. See the Agent Scoped Policies reference for how nodeId drives per-agent policy selection, and the Instrumentation Config reference for how hops are configured.

How Agent State Works

As a request flows through an agentic runtime (agent, orchestrator, gateway, tool), each hop can:

Read the incoming agent state from headers
Enrich it with hop-specific variables and metadata
Forward the updated state to the next hop

This creates a continuous context chain that enables downstream hops to make informed decisions and enables audit analytics across the full request graph.

State Structure

interface AgentStatePayload {
  nodeId: string;            // Logical node identifier (required)
  runId?: string;            // Run/inference identifier
  parentRef?: string;        // Parent hop reference

  variables?: {              // Scoped variables by hop type
    AGENT?: Record<string, any>;
    ORCHESTRATOR?: Record<string, any>;
    GATEWAY?: Record<string, any>;
    SERVER?: Record<string, any>;
    TOOL?: Record<string, any>;
  };

  metadata?: Record<string, any>;  // Arbitrary metadata
}

Variable Scopes

Each hop type writes to its own scope, preventing collisions:

Scope	Written By	Typical Contents
`AGENT`	Agent hops	Objective, execution reflections, status
`ORCHESTRATOR`	Orchestrator hops	Plan chain, workflow metadata
`GATEWAY`	Gateway hops	AP2 analytics, risk telemetry
`SERVER`	Server/middleware hops	Server-level signals, decision data
`TOOL`	Tool hops	Tool-specific state

Header Transport

Agent state is propagated across HTTP/MCP boundaries via three canonical headers:

Header	Content
`x-node-id`	The node identifier
`x-agent-ref`	The run/inference reference
`x-agent-state`	Base64-encoded full state payload

Encoding

import { encodeAgentStateHeaders } from "sec0-sdk/agent-state";

const headers = encodeAgentStateHeaders({
  nodeId: "planner",
  runId: "run-123",
  variables: {
    AGENT: { objective: "Find a PCP within 10 miles" },
  },
});
// Returns: { "x-node-id": "planner", "x-agent-ref": "run-123", "x-agent-state": "..." }

Decoding

import { extractAgentStateFromHeaders } from "sec0-sdk/agent-state";

const state = extractAgentStateFromHeaders(req.headers);
// state.nodeId, state.runId, state.variables, state.metadata

Merging Variables

import { mergeAgentVariables } from "sec0-sdk/agent-state";

// Merge new data into a specific scope (existing keys are overwritten)
const merged = mergeAgentVariables(existingVars, "GATEWAY", {
  gateway: "sec0.gateway@1.0.0",
  status: "ok",
});

Analytics Conventions

sec0-sdk/agent-state defines opt-in analytics payloads that higher-level components can include in agent state variables. These are never automatically enabled. Application authors must explicitly turn on the relevant telemetry flags.

Gateway Analytics

When analytics are enabled on the gateway, the GATEWAY scope contains:

{
  analytics: {
    version: 1,
    ap2?: {
      intent_id?: string;
      cart_id?: string;
      issuer_did?: string;
      subject_did?: string;
      constraints_sha256?: string;
      cart_sha256?: string;
      reason?: string;
    },
    risk?: {
      decision?: string;         // allow | deny | would_deny
      risk_tags?: string[];      // ['egress_violation', ...]
      egress_domain?: string;
      fs_path?: string;
      latency_ms?: number;
      idempotency_key?: string;
    }
  }
}

Orchestrator Plan Chain

Orchestrators can record their planned intent chain:

{
  orchestrator_plan: {
    version: 1,
    steps: [
      {
        id: "step-1",
        type: "tool",              // "tool" | "agent" | "action"
        target_tool?: "fetch@1.0",
        target_node_id?: "sub-agent",
        expected_args_sha256?: "...",
        metadata?: { model: "gpt-4o-mini" }
      }
    ]
  }
}

Agent Execution Reflection

Agents can reflect what actually occurred:

{
  agent_execution: {
    version: 1,
    runs: [
      {
        plan_step_id: "step-1",
        tool_invoked: "fetch@1.0",
        actual_args_sha256: "...",
        status: "ok",
        deviation_reason?: "unexpected_args",
        metadata?: { retries: 1 }
      }
    ]
  }
}

By keeping both plan and execution records in agent state, analytics can compute deviation metrics without inspecting raw prompts or payloads.

Safety Rules

Derived only: Never store raw mandates, secrets, or configuration in agent state
Version everything: Each payload has a version field for forward compatibility
Opt-in: Higher-level SDKs require an explicit toggle before adding telemetry to agent state

Getting Started

In-Device Security

Network Boundary Security

Policy & Compliance

Operations

Advanced

Reference

Agent State

Runtime Contextual Agent Governance

How Agent State Works

State Structure

Variable Scopes

Header Transport

Encoding

Decoding

Merging Variables

Analytics Conventions

Gateway Analytics

Orchestrator Plan Chain

Agent Execution Reflection

Safety Rules

​Runtime Contextual Agent Governance

​How Agent State Works

​State Structure

​Variable Scopes

​Header Transport

​Encoding

​Decoding

​Merging Variables

​Analytics Conventions

​Gateway Analytics

​Orchestrator Plan Chain

​Agent Execution Reflection

​Safety Rules

Runtime Contextual Agent Governance

How Agent State Works

State Structure

Variable Scopes

Header Transport

Encoding

Decoding

Merging Variables

Analytics Conventions

Gateway Analytics

Orchestrator Plan Chain

Agent Execution Reflection

Safety Rules