@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.
Ground truth for every export is the @guildai/agents-sdk package. See the SDK reference for full documentation. 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 |
|---|
guildTools | Platform tools (workspace context, credential requests, agent discovery, Guild service endpoints) |
userInterfaceTools | User interaction (prompt, notify, sleep) |
consoleTools | Debug logging tools (mirrors of task.console) |
noTools | Empty tool set — useful as an explicit “this agent needs no tools” marker |
Third-party service tools (for example gitHubTools) live in separate @guildai-services/* packages and are not re-exported from @guildai/agents-sdk. Import them alongside it.
Utilities
| Export | Description |
|---|
pick | Cherry-pick specific tools from a tool set |
omit | Drop specific tools from a tool set |
output | Return a final result from a SelfManagedStateAgent |
callTools | Return a tool call request from a SelfManagedStateAgent |
ask | Shortcut for callTools([...]) that asks the user a text prompt |
progressLogNotifyEvent | Construct a progress log event for task.ui.notify() |
textPromptNotifyEvent | Construct a text-prompt notification event |
errorNotifyEvent | Construct an error notification event |
guildAgentTool | Create a custom tool that dispatches to another Guild agent |
guildServiceTool | Create a custom tool wrapping a Guild service endpoint with a transformed output schema |
Task object
The Task object passed to every agent’s run function provides access to platform services:
| Property | Description | Availability |
|---|
task.sessionId | Opaque session identifier used to correlate operations | Always available |
task.console | Debug logging (debug, info, warn, error, log) | Always available |
task.tools | Typed proxy for all declared tools | Always available |
task.llm | LLM calls via generateText() | Always available |
task.save / task.restore | Persist and retrieve agent state between invocations | Always available |
task.guild | Platform operations (workspace context, credentials, service APIs) | Requires guildTools |
task.ui | User interaction and notifications | Requires userInterfaceTools |
