@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
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 | llmAgent | AutomaticallyManagedStateAgent | SelfManagedStateAgent |
|---|---|---|---|
| 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.
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.