@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. Because agents can be suspended when they make tool or subagent calls, their state must be saved on suspend and restored on resume. This state can be managed for you to maximize simplicity, or you can manage it yourself for maximum flexibility and control.
Agent types
llmAgent
An LLM that follows a system prompt and uses tools to accomplish a task. The
simplest way to build an agent.
AutomaticallyManagedStateAgent
A TypeScript function that runs to completion. Deterministic,
cost-predictable, and suitable for algorithmic tasks.
SelfManagedStateAgent
An event-driven agent for parallel tool calls and fine-grained state
control.
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.
Agents run in a sandboxed environment. You can only import
@guildai/agents-sdk, zod, and @guildai-services/* packages — other npm
packages and Node.js built-in modules are not available.Next steps
LLM agents
Build prompt-driven agents with tools.
Coded agents
Build deterministic TypeScript agents.
Task object
Access LLMs, platform services, and user interaction.
Tool sets
Pre-built tool sets for platform operations, user prompts, and debug
logging.