@guildai/agents-sdk

@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 Agent SDK introduction 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

See LLM agents and Coded agents for usage.

Tool sets

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.

See Tool sets for details on each tool set.

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` notify event for `task.ui.notify()`
`textPromptNotifyEvent`	Construct a `message` notify event with text content
`errorNotifyEvent`	Construct an `error` notify event
`guildAttachmentNotifyEvent`	Construct an `application/guild-attachment` notify event that renders a stored image or PDF in the UI
`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.env`	Docker container management	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`

See Task object for the full API.

Reference

Configuration

@guildai/agents-sdk

Agent constructors

Tool sets

Utilities

Task object

​Agent constructors

​Tool sets

​Utilities

​Task object

Agent constructors

Tool sets

Utilities

Task object