Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.guild.ai/llms.txt

Use this file to discover all available pages before exploring further.

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.

​
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

ConsiderationAuto-managedSelf-managed
BoilerplateMinimalMore
Parallel tool callsNoYes
Serialization constraintsYesNone
State visibilityImplicitExplicit
Recommended forMost agentsComplex workflows