The State class provides a way to manage state and history across a network of agents. It includes key-value storage and maintains a stack of all agent interactions.

The State is accessible to all Agents, Tools and Routers as a state or network.state property.

Creating a State

import { State } from '@inngest/agent-kit';

const state = new State({
  foo: 'bar',
});

console.log(state.kv.get('foo')); // 'bar'


const network = createNetwork({
  // ...
});

network.run("<query>", { state })

Reading and Modifying State (state.kv)

The State class provides a key-value store accessible via the kv property.

Learn more about the State use cases in the State concept guide.

kv.set
function

Set a value in the key-value store.

kv.set<T>(key: string, value: T): void
kv.get
function

Get a value from the key-value store.

kv.get<T>(key: string): T | undefined
kv.delete
function

Delete a key from the store.

kv.delete(key: string): boolean
kv.has
function

Check if a key exists in the store.

kv.has(key: string): boolean
kv.all
function

Get all key-value pairs as a record.

kv.all(): Record<string, unknown>

State History

The State history is passed as a history to the lifecycle hooks and via the network argument to the Tools handlers to the Router function.

The State history can be retrieved - as a copy - using the state.results property composed of InferenceResult objects:

InferenceResult

The InferenceResult class represents a single agent call as part of the network state. It stores all inputs and outputs for a call.

agent
Agent

The agent responsible for this inference call.

input
string

The input passed into the agent’s run method.

prompt
Message[]

The input instructions without additional history, including the system prompt, user input, and initial agent assistant message.

history
Message[]

The history sent to the inference call, appended to the prompt to form a complete conversation log.

output
Message[]

The parsed output from the inference call.

toolCalls
ToolResultMessage[]

Output from any tools called by the agent.

raw
string

The raw API response from the call in JSON format.

Message Types

The state system uses several message types to represent different kinds of interactions:

type Message = TextMessage | ToolCallMessage | ToolResultMessage;

interface TextMessage {
  type: "text";
  role: "system" | "user" | "assistant";
  content: string | Array<TextContent>;
  stop_reason?: "tool" | "stop";
}

interface ToolCallMessage {
  type: "tool_call";
  role: "user" | "assistant";
  tools: ToolMessage[];
  stop_reason: "tool";
}

interface ToolResultMessage {
  type: "tool_result";
  role: "tool_result";
  tool: ToolMessage;
  content: unknown;
  stop_reason: "tool";
}