> ## 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.

# @guildai/agents-sdk

> The core SDK package for building Guild agents.

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

## 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](/guide/llm-agents) and [Coded 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`                   | 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](/sdk/task-object) for the full API.