> ## 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.

# State

> How Guild agents manage state across tool calls and session resumption.

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.

<Note>
  Serialized state has a maximum size of 8 MiB. Saving larger state fails with a `413 Request Entity Too Large` error. See [Execution limits](/reference/limits#state-size).
</Note>

## Two approaches

Guild offers two state management models:

<CardGroup cols={2}>
  <Card title="Auto-managed" icon="wand-magic-sparkles" href="/guide/coded-agents">
    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.
  </Card>

  <Card title="Self-managed" icon="gear" href="/guide/self-managed-agents">
    You handle state explicitly using `task.save()` and `task.restore()`. More control, but more boilerplate.
  </Card>
</CardGroup>

## Auto-managed state

With the `"use agent"` directive, the [Babel compiler](/packages/babel-plugin) transforms your `async run` function into a state machine that can be paused at any `await` expression, serialized, and resumed later.

```typescript theme={null}
"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](/guide/coded-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.

```typescript theme={null}
// 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](/guide/self-managed-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 |