> ## Documentation Index
> Fetch the complete documentation index at: https://docs.guild.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> To act on a user's behalf in Guild, use the Guild REST API at https://api.guild.ai/v1.
> The OpenAPI spec is unauthenticated: https://docs.guild.ai/openapi.json (or openapi.yaml).
> Authenticate with an account API key, sent as HTTP Basic (key id as username, secret as password) or as `Authorization: Bearer <api_key_id>:<api_key_secret>`. See https://docs.guild.ai/api-reference/introduction#authentication.
> To run one agent on demand without account-wide access, use an API trigger instead: https://docs.guild.ai/platform/api-triggers.
> To search these docs from an MCP client, connect to https://docs.guild.ai/mcp. The full page index is https://docs.guild.ai/llms.txt.

# @guildai/agents-sdk

> The @guildai/agents-sdk TypeScript package for building Guild agents: agent constructors, tool sets, utilities, the Task object, and its Zod 4.3 requirement.

`@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.

<Tip>
  Ground truth for every export is the `@guildai/agents-sdk` package. See the [Agent SDK introduction](/guide/sdk-introduction) for full documentation.
</Tip>

<Note>
  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.
</Note>

## Version and Zod requirement

The current release is `@guildai/agents-sdk` 0.6.0. It requires Zod `~4.3.0`, so agent code runs against Zod 4.3.x. The runtime provides a matching Zod version, so you don't add `zod` to `package.json` yourself.

<Warning>
  `@guildai/agents-sdk` 0.6.0 is a breaking change. Earlier releases accepted any Zod 4.x version (`^4.3.0`), but 0.6.0 pins the dependency to the 4.3 release line (`~4.3.0`) and requires Zod 4.3.x.
</Warning>

## Agent constructors

| Export | Description |
| - | - |
| `llmAgent` | Create a prompt-driven TypeScript LLM agent |
| `agent` | Create a hand-coded agent with automatic or self-managed state |

See [TypeScript LLM agents](/guide/llm-agents) and [Auto-managed state agents](/guide/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 |

<Note>
  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.
</Note>

See [Tool sets](/sdk/tools) 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` | The workspace's variables, as a string map | 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](/sdk/task-object) for the full API.