State

Guild agents often need to pause execution — waiting for a tool to complete, a user to respond, or an external service to return data. State management determines how your agent’s in-progress work is preserved and restored across these pauses.

Serialized state has a maximum size of 8 MiB. Saving larger state fails with a 413 Request Entity Too Large error. See Execution limits.

Two approaches

Guild offers two state management models:

Auto-managed

The runtime handles state automatically. Write a normal async function with the "use agent" directive — the Babel compiler transforms it into a resumable state machine.

Self-managed

You handle state explicitly using task.save() and task.restore(). More control, but more boilerplate.

Auto-managed state

With the "use agent" directive, the Babel compiler transforms your async run function into a state machine that can be paused at any await expression, serialized, and resumed later.

"use agent"

async function run(input: Input, task: Task<Tools>): Promise<Output> {
  // This function can be paused and resumed transparently
  const issue = await task.tools.github_issues_get({ ... })
  const summary = await task.llm.generateText({ prompt: issue.body })
  return { summary: summary.text }
}

Limitations:

No Promise.all, Promise.any, or Promise.race across await points
Dynamic function references may not survive serialization
Only code in the agent file is compiled (imports are not traversed)

See Auto-managed state agents for full details.

Self-managed state

With SelfManagedStateAgent, you define a stateSchema and use task.save() / task.restore() to explicitly persist and retrieve state between tool calls.

// Save state before requesting tool calls
await task.save({ step: "processing", items: collected })

// Restore state when tool results arrive
const state = await task.restore()

Advantages:

Parallel tool calls via callTools([...])
Full control over what gets persisted
No compiler limitations

See Self-managed state agents for full details.

Choosing a model

Consideration	Auto-managed	Self-managed
Boilerplate	Minimal	More
Parallel tool calls	No	Yes
Serialization constraints	Yes	None
State visibility	Implicit	Explicit
Recommended for	Most agents	Complex workflows

Overview

The Smith

Platform

Insights

Agent SDK

Two approaches

Auto-managed

Self-managed

Auto-managed state

Self-managed state

Choosing a model

​Two approaches

Auto-managed

Self-managed

​Auto-managed state

​Self-managed state

​Choosing a model

Two approaches

Auto-managed state

Self-managed state

Choosing a model