Task object

Every agent callback — run, start, onToolResults, init — receives a Task object as its last argument. The task is your agent’s interface to the Guild runtime: it exposes services for calling platform endpoints, talking to the user, logging, and persisting state.

async function run(input: Input, task: Task<Tools>): Promise<Output> {
  // task.sessionId, task.console, task.tools
  // task.guild, task.ui, task.llm
  // task.save, task.restore
}

The shape of task is conditional on the Tools type: task.guild is typed as GuildService only when Tools structurally extends GuildToolSet, and task.ui is UserInterfaceService only when Tools extends UserInterfaceToolSet. Including the corresponding tool set in your agent’s tools is how you “turn on” the service.

Typical usage

Most agents only need a handful of services. Here’s a small agent that uses task.console, task.ui, and task.guild:

import {
  agent,
  guildTools,
  progressLogNotifyEvent,
  userInterfaceTools,
  type Task,
} from "@guildai/agents-sdk"
import { z } from "zod"

const inputSchema = z.object({ workspace_id: z.string() })
const outputSchema = z.object({
  workspace_name: z.string(),
  context_count: z.number(),
})

const tools = { ...guildTools, ...userInterfaceTools }
type Tools = typeof tools

async function run(
  input: z.infer<typeof inputSchema>,
  task: Task<Tools>,
): Promise<z.infer<typeof outputSchema>> {
  "use agent"
  task.console.info({ sessionId: task.sessionId }, "starting run")

  await task.ui.notify(progressLogNotifyEvent("Fetching workspace..."))
  const workspace = await task.guild!.get_workspace({
    workspace_id: input.workspace_id,
  })

  await task.ui.notify(progressLogNotifyEvent("Checking context history..."))
  const { items } = await task.guild!.get_workspace_contexts({
    workspace_id: input.workspace_id,
    limit: 100,
  })

  return { workspace_name: workspace.name, context_count: items.length }
}

export default agent({
  description: "Typical task usage.",
  inputSchema,
  outputSchema,
  tools,
  run,
})

`task.sessionId`

The opaque session identifier for the current agent run. Use it to correlate logs, emit metrics, or pass to endpoints that take a session id.

task.console.debug({ sessionId: task.sessionId }, "starting work")

`task.console` — debug logging

task.console is always available and never requires a tool set. Use it for printf-style debugging visible in the runtime logs. Each level accepts either a message string, an object + message, or arbitrary variadic arguments.

Method	Description
`debug(msg or obj, ...args)`	Debug-level message
`info(msg or obj, ...args)`	Info-level message
`warn(msg or obj, ...args)`	Warning message
`error(msg or obj, ...args)`	Error message
`log(msg or obj, ...args)`	Alias for `info`
`console_log({ level, message })`	Structured variant matching the `console_log` tool

await task.console.debug({ input }, "received request")
await task.console.error("aborting: invalid state")

To expose debug logging to an LLM, include consoleTools in your agent — the LLM can then call console_log as a regular tool.

`task.tools` — invoke your tools directly

task.tools is a typed proxy over every tool declared in the agent’s tools set. Calling task.tools.foo(args) dispatches to the tool and returns its output with the tool’s declared output type.

const workspace = await task.tools.guild_get_workspace({
  workspace_id: "ws_123",
})

This works for any tool, whether it’s a built-in tool set (guildTools, userInterfaceTools, …), a third-party service tool (gitHubTools), or a custom tool created with guildServiceTool / guildAgentTool.

`task.ui` — user interaction

Available when Tools includes userInterfaceTools. task.ui is a UserInterfaceService that can send notifications, ask the user for input, or ping the front-end.

Method	Description
`notify(event)`	Fire-and-forget notification. Use the event helpers listed below.
`prompt({ type: "text", text })`	Block until the user replies with text.
`ping({ message })`	Health-check the UI surface (mostly for testing).

Notify event helpers

notify takes a discriminated NotifyEvent. Three helpers in @guildai/agents-sdk construct the common shapes:

Helper	Event type	Use for
`progressLogNotifyEvent(text)`	`progress`	Non-intrusive “Creating…”, “Running…” status updates during long work
`textPromptNotifyEvent({ type: "text", text })`	`message`	A regular message posted to the conversation
`errorNotifyEvent(error)`	`error`	Prominently-displayed error condition

import {
  progressLogNotifyEvent,
  textPromptNotifyEvent,
  errorNotifyEvent,
} from "@guildai/agents-sdk"

await task.ui.notify(progressLogNotifyEvent("Creating environment..."))
await task.ui.notify(
  textPromptNotifyEvent({ type: "text", text: "Here's what I found." }),
)
await task.ui.notify(errorNotifyEvent("Failed to reach GitHub"))

Prompting the user

task.ui.prompt blocks the agent until the user replies. It’s the imperative counterpart to the ask(...) helper used by self-managed agents.

const reply = await task.ui.prompt({
  type: "text",
  text: "Which language should I use?",
})
// reply.text contains the user's answer

Progress log best practices

Use present continuous tense: “Creating…”, “Running…”, “Writing…”
Keep messages to one line
Be specific: “Writing 3 files…” rather than “Processing…”
Log at meaningful milestones, not on every iteration

`task.llm` — LLM calls

task.llm always exposes an LLMService. The runtime handles authentication and provider selection, so you don’t need to pass API keys or pick a model explicitly.

Method	Description
`generateText(params)`	Call the workspace’s configured LLM. Returns `{ text, content, toolCalls, toolResults, finishReason, response }`.

generateText takes either a single prompt or a messages array, never both:

const result = await task.llm.generateText({
  prompt: "Summarize this file:\n\n" + source,
})
// result.text — plain-text summary

const chat = await task.llm.generateText({
  system: "You are a concise assistant.",
  messages: [
    { role: "user", content: "What is Guild?" },
  ],
})

Pass tools to generateText if you want the LLM to request tool calls; the returned toolCalls array lists what it decided to invoke.

`task.save` / `task.restore` — state persistence

Used by SelfManagedStateAgent (and available to automatic-state agents too):

Method	Description
`save(state)`	Persist `state` to the runtime. Must match `stateSchema` and be JSON-serializable.
`restore()`	Read the previously-saved state, or `undefined` if nothing is saved yet.

State is scoped to the current task, and is retained across suspensions (e.g., while waiting for user input).

`task.guild` — platform operations

Available when Tools structurally includes GuildToolSet. task.guild is a GuildService that exposes the full Guild platform API — workspaces, agents, triggers, credentials, sessions, and escape hatches like experimental_fetch. Because task.guild is conditionally typed, TypeScript types it as GuildService | undefined until it can prove your tool set includes guildTools. A common pattern is to assert non-null with ! after ensuring guildTools is in the spread:

const tools = { ...guildTools }
// ...
const { items } = await task.guild!.get_workspace_contexts({
  workspace_id: input.workspace_id,
  limit: 10,
})

The 50+ endpoints below are grouped by theme. All of them take a single params object and return a structured response; each takes a single params object and returns a structured response.

Current user

Endpoint	Description
`get_me`	Fetch the authenticated user’s profile
`update_me`	Update the authenticated user’s profile
`get_my_workspaces`	List workspaces owned by or visible to the current user
`get_my_organizations`	List organizations the current user belongs to
`get_my_sessions`	List recent sessions for the current user

Users

Endpoint	Description
`search_users`	Full-text search across users
`get_user`	Look up a specific user by id
`get_user_organizations`	List organizations a user belongs to
`get_user_agents`	List agents a user has authored
`get_user_workspaces`	List workspaces a user can access

Agents

Endpoint	Description
`list_agents`	Paginated list of agents
`search_agent`	Keyword search across agents
`check_agent_name`	Check whether an agent name is available
`get_agent`	Fetch a single agent by id
`create_agent`	Create a new agent
`update_agent`	Update an existing agent
`get_agent_code`	Read the source code of an agent version
`list_agent_versions`	List historical versions of an agent
`create_agent_version`	Publish a new version of an agent
`get_agent_version`	Fetch a specific version by id
`revalidate_agent_version`	Rerun validation on an existing version
`list_agent_tags`	List tags attached to an agent
`update_agent_tags`	Replace the set of tags on an agent
`generate_agent_avatar`	Generate an avatar image for an agent

Agent likes

Endpoint	Description
`create_agent_like`	Like an agent on behalf of the current user
`delete_agent_like`	Unlike an agent
`list_agent_likers`	List the users who have liked a given agent
`list_agent_workspaces`	List the workspaces that have installed a given agent

Organizations

Endpoint	Description
`get_organization`	Fetch an organization by id
`update_organization`	Update an organization
`get_organization_workspaces`	List workspaces in an organization
`get_organization_agents`	List agents in an organization
`get_organization_members`	List members of an organization

Workspaces

Endpoint	Description
`get_workspace`	Fetch a workspace by id
`get_workspace_agents`	List agents installed in a workspace
`get_workspace_sessions`	List sessions in a workspace
`get_workspace_contexts`	List versions of the workspace context (newest first)
`create_workspace_context`	Append a new `DRAFT` or `PUBLISHED` workspace context version

Triggers

Endpoint	Description
`get_workspace_triggers`	List triggers in a workspace
`create_workspace_trigger`	Create a new trigger
`get_trigger`	Fetch a trigger by id
`update_trigger`	Update a trigger
`activate_trigger`	Enable a trigger
`deactivate_trigger`	Disable a trigger
`get_trigger_sessions`	List sessions created by a trigger

Sessions & tasks

Endpoint	Description
`get_session`	Fetch a session by id
`get_task_workspace_agents`	List workspace agents available to the current task (used internally by `llmAgent`)

LLM usage

Endpoint	Description
`get_daily_llm_usage`	Daily token usage rollups
`get_hourly_llm_usage`	Hourly token usage rollups

Credentials & install hooks

These endpoints may suspend the agent while waiting for a user or GitHub to respond.

Endpoint	Description
`agent_install_request`	Ask the user to install another agent into the workspace
`credentials_request`	Ask the user to authorize a third-party service (e.g., Linear, GitHub)
`experimental_github_installation_token`	Mint a GitHub installation token for the current workspace

Flow control & HTTP

Endpoint	Description
`sleep`	Suspend the agent for N seconds (may round-trip the runtime)
`experimental_fetch`	Synchronous HTTP request
`experimental_fetch_async`	Async HTTP request — result arrives via a hook when complete

Service availability

Property	When available
`task.sessionId`	Always
`task.console`	Always
`task.tools`	Always — contains your declared tools
`task.llm`	Always
`task.save` / `task.restore`	Always
`task.ui`	Requires `userInterfaceTools` in `tools`
`task.guild`	Requires `guildTools` in `tools`

Overview

Building agents

Packages

Typical usage

`task.sessionId`

`task.console` — debug logging

`task.tools` — invoke your tools directly

`task.ui` — user interaction

Notify event helpers

Prompting the user

Progress log best practices

`task.llm` — LLM calls

`task.save` / `task.restore` — state persistence

`task.guild` — platform operations

Current user

Users

Agents

Agent likes

Organizations

Workspaces

Triggers

Sessions & tasks

LLM usage

Credentials & install hooks

Flow control & HTTP

Service availability

Overview

Building agents

Packages

​Typical usage

​task.sessionId

​task.console — debug logging

​task.tools — invoke your tools directly

​task.ui — user interaction

​Notify event helpers

​Prompting the user

​Progress log best practices

​task.llm — LLM calls

​task.save / task.restore — state persistence

​task.guild — platform operations

​Current user

​Users

​Agents

​Agent likes

​Organizations

​Workspaces

​Triggers

​Sessions & tasks

​LLM usage

​Credentials & install hooks

​Flow control & HTTP

​Service availability

Typical usage

`task.sessionId`

`task.console` — debug logging

`task.tools` — invoke your tools directly

`task.ui` — user interaction

Notify event helpers

Prompting the user

Progress log best practices

`task.llm` — LLM calls

`task.save` / `task.restore` — state persistence

`task.guild` — platform operations

Current user

Users

Agents

Agent likes

Organizations

Workspaces

Triggers

Sessions & tasks

LLM usage

Credentials & install hooks

Flow control & HTTP

Service availability