Skip to main content
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 four agent types, each with different trade-offs:

LLM agents

An LLM that follows a system prompt and uses tools to accomplish a task. The simplest way to build an agent.

Auto-managed state agents

A TypeScript function that runs to completion. Deterministic, cost-predictable, and suitable for algorithmic tasks.

Self-managed state agents

An event-driven agent for parallel tool calls and fine-grained state control.

Goose agents

An agent defined by a recipe.yaml file in the Goose recipe format. No TypeScript required.
Guild also supports Guild Native and Goose agent architectures, which use Markdown and YAML files instead of TypeScript code. See Agent types for a full overview.

​
Choosing an agent type

​
Agent type identifiers

Every agent has a mandatory agent_type property that identifies how it is implemented. The platform sets this value automatically and exposes it in the Ops Inspector and the platform API.

​
Agent schema

Every agent declares:
  • description — (optional, deprecated as of @guildai/agents-sdk 0.4.0) Guild generates the agent’s published description automatically from its code, so setting description in code no longer affects the published description.
  • 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.
inputSchema must be z.object({ ... }) at the root. Do not use z.union() or z.discriminatedUnion() at the root. LLM providers require "type": "object" at the top of tool input schemas, and other root types cause validation failures at runtime.
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.

​
Next steps

LLM agents

Build prompt-driven agents with tools.

Auto-managed state agents

Build deterministic TypeScript agents.

Self-managed state agents

Build event-driven agents with explicit state control.

Tasks

Access LLMs, Docker environments, and platform services at runtime.