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.env
  // 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(),
  agent_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("Listing installed agents..."))
  const { items } = await task.guild!.get_workspace_agents({
    workspace_id: input.workspace_id,
    limit: 100,
  })

  return { workspace_name: workspace.name, agent_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.gather` — concurrent tool calls

task.gather runs an array of tool or sub-agent calls concurrently. It has Promise.all semantics: if any call fails, the entire batch rejects with that error. If all calls succeed, it resolves to an array of results in source order.

const [pr, comments] = await task.gather([
  task.tools.github_pulls_get({ owner: "myorg", repo: "myrepo", pull_number: 123 }),
  task.tools.github_issues_list_comments({ owner: "myorg", repo: "myrepo", issue_number: 123 }),
])

Under the hood, synchronous tool calls execute in-process on a fast path. Deferred calls — such as sub-agent invocations — are batched: the agent’s state machine suspends, all deferred calls are dispatched together, and execution resumes once every call has settled. Results are always returned in source order.

`task.gatherSettled` — concurrent calls with individual outcomes

task.gatherSettled runs an array of tool or sub-agent calls concurrently. It has Promise.allSettled semantics: it never rejects. Instead, it resolves to an array of PromiseSettledResult objects in source order, each containing either { status: "fulfilled", value: result } or { status: "rejected", reason: Error }. Use task.gatherSettled when you want to inspect per-call failures rather than stopping the entire batch on the first error.

const results = await task.gatherSettled([
  task.tools.github_pulls_get({ owner: "myorg", repo: "myrepo", pull_number: 1 }),
  task.tools.github_pulls_get({ owner: "myorg", repo: "myrepo", pull_number: 2 }),
])

for (const result of results) {
  if (result.status === "fulfilled") {
    console.log("PR title:", result.value.title)
  } else {
    console.error("Failed:", result.reason)
  }
}

The execution model is the same as task.gather: synchronous calls take the fast path, and deferred calls are batched and resumed together.

`task.env` — workspace variables

task.env is always available. It holds the workspace’s variables, resolved when the task dispatches or resumes.

const repo = task.env.GITHUB_REPO

Keys are uppercase identifiers. Reading a key that has no value throws, naming the key — it never returns undefined, so a missing variable fails loudly instead of silently becoming undefined deep in your agent. Values are stable within a turn and refreshed between turns, so an edit made mid-task takes effect on the next resume at the earliest.

task.env does not create or manage containers. To run code in a container, use the guildai~experimental-coding integration through task.tools — see Running code in a container.

Running code in a container

Container-backed coding environments are an integration, reached through task.tools like any other:

Tool	Description
`experimental_coding_create`	Create a container and run its setup phase. Suspends the task until setup finishes, then returns a `container_id`.
`experimental_coding_communicate`	Send a message to the container and collect its response.
`experimental_coding_delete`	Stop and remove the container.

experimental_coding_create takes an environment (an owner~name runtime environment, preferred) or an image, plus optional env variables for the setup script, a timeout in seconds (default 600), and debug_mode to stream setup output to the runtime detail page.

The setup script is owner-declared — it lives on the runtime environment, not on the call — so a caller cannot supply one. An environment with no setup script makes setup a no-op.

Setup output is captured line-by-line as container event logs. The runtime detail page has a scrollable Logs table showing that output with a timestamp per line, up to 2,000 lines. Error lines stream regardless of debug_mode; other setup output streams only when you enable it.

`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 with message, progress, or error types. These helpers in @guildai/agents-sdk construct the supported 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 session
`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

task.ui is available when your agent includes userInterfaceTools.

Progress logging

Progress logs give users real-time feedback during long-running operations. They appear inline without requiring user interaction.

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

await task.ui?.notify(progressLogNotifyEvent("Creating coding environment..."))
const { container_id } = await task.tools.experimental_coding_create({
  environment: "myorg~node-20",
})

await task.ui?.notify(progressLogNotifyEvent("Running tests..."))
const result = await task.tools.experimental_coding_communicate({
  container_id,
  message: "Run the test suite and report the results.",
})

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. Pass llmPreferences to request specific providers or models for the call. Preferences are strict: if none of them is permitted by the account’s keys and policies, the call fails rather than falling back to the default model. See LLM preferences.

`generateText` makes a single model call

generateText sends the messages, gets one response back, and returns. There is no maxSteps and no stopWhen, so there is no built-in ReAct loop. Tools you pass with an execute function are run, so result.toolResults may be populated — but the model is never called again with those results. A turn that ends in a tool call comes back with finishReason: "tool-calls" and text that stops mid-thought. If the agent must call a tool, read what it returned, and continue, write that loop yourself:

import type { ModelMessage } from "@guildai/agents-sdk"

const messages: ModelMessage[] = [{ role: "user", content: input.text }]

for (let step = 0; step < MAX_TOOL_STEPS; step++) {
  const result = await task.llm.generateText({ system, messages, tools })

  // No tool calls: the model is done and result.text is the answer.
  if (result.toolCalls.length === 0) return { text: result.text }

  // Feed the assistant turn and the tool results back in, then go round again.
  messages.push(...result.response.messages)
  messages.push({
    role: "tool",
    content: asToolResultContent(await dispatch(result.toolCalls)),
  })
}

dispatch and asToolResultContent are yours to write — the first runs the calls, the second shapes them into tool-result content parts. Bound the loop clear of normal use: a ceiling a legitimate request can reach truncates that request silently. If you would rather not write the loop, llmAgent is the managed version, and a self-managed agent’s start() / onToolResults() pair lets the runtime drive the round trip. Hand-roll only when you need control over each step.

`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, and sessions. 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_agents({
  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
`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`	Look up a user by exact username (case-insensitive)
`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. Accepts `agent_types` (comma-separated) to filter by agent type.
`get_user_workspaces`	List workspaces a user can access

Agents

Endpoint	Description
`list_agents`	Paginated list of agents. Accepts `agent_types` (comma-separated) to filter by agent type.
`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, or fork an existing committed version with `mode: "fork"`
`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. Accepts `agent_types` (comma-separated) to filter by agent type.
`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_default_chat_agent`	Fetch the agent a workspace uses for chat by default

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`). Accepts `agent_types` (comma-separated) to filter by agent type.

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 the user 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)

Flow control

Endpoint	Description
`sleep`	Suspend the agent for N seconds (may round-trip the runtime)

task.guild makes no outbound HTTP requests on your behalf. To fetch an arbitrary URL, use the guildai~experimental-fetch integration — see Fetching an arbitrary URL.

Service availability

Property	When available
`task.sessionId`	Always
`task.console`	Always
`task.tools`	Always — contains your declared tools
`task.gather` / `task.gatherSettled`	Always
`task.llm`	Always
`task.env`	Always — the workspace’s variables
`task.ui`	Requires `userInterfaceTools` in tools
`task.guild`	Requires `guildTools` in tools
`task.save()` / `task.restore()`	`SelfManagedStateAgent` only

Reference

Configuration

Typical usage

`task.sessionId`

`task.console` — debug logging

`task.tools` — invoke your tools directly

`task.gather` — concurrent tool calls

`task.gatherSettled` — concurrent calls with individual outcomes

`task.env` — workspace variables

Running code in a container

`task.ui` — user interaction

Notify event helpers

Prompting the user

Progress logging

`task.llm` — LLM calls

`generateText` makes a single model call

`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

Service availability

​Typical usage

​task.sessionId

​task.console — debug logging

​task.tools — invoke your tools directly

​task.gather — concurrent tool calls

​task.gatherSettled — concurrent calls with individual outcomes

​task.env — workspace variables

​Running code in a container

​task.ui — user interaction

​Notify event helpers

​Prompting the user

​Progress logging

​task.llm — LLM calls

​generateText makes a single model call

​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

​Service availability

Typical usage

`task.sessionId`

`task.console` — debug logging

`task.tools` — invoke your tools directly

`task.gather` — concurrent tool calls

`task.gatherSettled` — concurrent calls with individual outcomes

`task.env` — workspace variables

Running code in a container

`task.ui` — user interaction

Notify event helpers

Prompting the user

Progress logging

`task.llm` — LLM calls

`generateText` makes a single model call

`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

Service availability