Skip to main content
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:
ContextPurposeGovernance Use
nodeIdIdentifies which agent/hop is executingResolves agent-scoped policy for this node
runIdLinks all hops in a single request graphCorrelates audit trail across distributed hops
variablesScoped key-value pairs per hop typeCompliance rules can inspect objective, plan, and execution state
metadataArbitrary data attached by each hopEnriches audit envelopes with model, temperature, etc.
parentRefReference to the parent hopReconstructs 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:
  1. Read the incoming agent state from headers
  2. Enrich it with hop-specific variables and metadata
  3. 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:
ScopeWritten ByTypical Contents
AGENTAgent hopsObjective, execution reflections, status
ORCHESTRATOROrchestrator hopsPlan chain, workflow metadata
GATEWAYGateway hopsAP2 analytics, risk telemetry
SERVERServer/middleware hopsServer-level signals, decision data
TOOLTool hopsTool-specific state

​
Header Transport

Agent state is propagated across HTTP/MCP boundaries via three canonical headers:
HeaderContent
x-node-idThe node identifier
x-agent-refThe run/inference reference
x-agent-stateBase64-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

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