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

# Agent SDK

> Overview of the Guild Agent SDK and how to choose an agent type.

The `@guildai/agents-sdk` package provides types, utilities, tool sets, and platform service interfaces for building Guild agents.

An agent takes typed input, does its work using tools, LLMs, or other agents, and returns typed output.

## Agent types

Guild supports three agent types, each with different trade-offs:

<CardGroup cols={1}>
  <Card title="LLM agents" icon="brain" href="/guide/llm-agents">
    An LLM that follows a system prompt and uses tools to accomplish a task. The simplest way to build an agent.
  </Card>

  <Card title="Auto-managed state agents" icon="code" href="/guide/coded-agents">
    A TypeScript function that runs to completion. Deterministic, cost-predictable, and suitable for algorithmic tasks.
  </Card>

  <Card title="Self-managed state agents" icon="gear" href="/guide/self-managed-agents">
    An event-driven agent for parallel tool calls and fine-grained state control.
  </Card>
</CardGroup>

## Choosing an agent type

| Feature      | LLM agent                             | Auto-managed state    | Self-managed state                 |
| ------------ | ------------------------------------- | --------------------- | ---------------------------------- |
| **Ease**     | Easy                                  | Moderate              | Challenging                        |
| **Control**  | Stochastic                            | Deterministic         | Deterministic                      |
| **LLM cost** | Variable                              | Fixed                 | Fixed                              |
| **Best for** | Tasks expressible as a prompt + tools | Algorithmic workflows | Parallel tool calls, complex state |

## Agent schema

Every agent must declare:

* **`description`** — Used by humans and LLMs to determine when to invoke the agent.
* **`inputSchema`** — A Zod schema describing the agent's input.
* **`outputSchema`** — A Zod schema describing the agent's output.
* **`tools`** — (optional) Tools the agent may use.

<Note>
  The runtime only supports `@guildai/agents-sdk` and `zod`. You cannot import external npm packages or Node.js built-in modules — agents run in a sandboxed environment.
</Note>

## Next steps

<CardGroup cols={2}>
  <Card title="LLM agents" icon="brain" href="/guide/llm-agents">
    Build prompt-driven agents with tools.
  </Card>

  <Card title="Auto-managed state agents" icon="code" href="/guide/coded-agents">
    Build deterministic TypeScript agents.
  </Card>

  <Card title="Self-managed state agents" icon="gear" href="/guide/self-managed-agents">
    Build event-driven agents with explicit state control.
  </Card>

  <Card title="Tasks" icon="server" href="/guide/tasks">
    Access LLMs, Docker environments, and platform services at runtime.
  </Card>
</CardGroup>