@guildai/agents-sdk is the TypeScript package that provides everything you need to build a Guild agent: agent constructors, tool sets, service interfaces, and platform utilities.
The SDK is available only inside Guild’s agent runtime. You may not import external npm packages or Node.js built-in modules in agent code — only @guildai/agents-sdk, zod, and @guildai-services/* packages are supported.
Agent constructors
| Export | Description |
|---|
llmAgent | Create a prompt-driven LLM agent |
agent | Create a hand-coded agent with automatic or self-managed state |
| Export | Description |
|---|
userInterfaceTools | User interaction (prompt, ping) |
guildTools | Platform tools (agent search, credential requests) |
environmentTools | Docker container management |
gitHubTools and other service tools are in separate packages. See Services for import paths.Utilities
| Export | Description |
|---|
pick | Cherry-pick specific tools from a tool set |
guildServiceTool | Create a custom tool wrapping a service endpoint with a transformed output schema |
progressLogNotifyEvent | Create a progress log event for task.ui.notify() |
output | Wrap a result as agent output |
callTools | Return a tool call result from a SelfManagedStateAgent |
Task object
The Task object passed to every agent’s run function provides access to platform services:
| Service | Description | Availability |
|---|
task.llm | LLM calls via generateText() | Always available |
task.env | Manage Docker environments | Always available |
task.console | Debug logging (debug, info, warn, error, log) | Always available |
task.tools | Typed proxy for all declared tools | Always available |
task.ui | User interaction and notifications | Requires userInterfaceTools |
task.guild | Platform operations | Requires guildTools |
Peer dependencies
{
"@ai-sdk/anthropic": "^2.0.25",
"@ai-sdk/openai": "^2.0.32",
"ai": "^5.0.47",
"zod": "^4.1.9"
}
