Tasks and runtime services

Every agent receives a Task object as its second argument. The task is your agent’s interface to the Guild runtime — it provides access to tools, LLMs, workspace variables, user interaction, and platform services.

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

Available services

Service	Description	Availability
`task.tools`	Typed proxy for all declared tools	Always
`task.gather` / `task.gatherSettled`	Concurrent tool execution	Always
`task.llm`	LLM calls via `generateText()`	Always
`task.env`	The workspace’s variables, as a string map	Always
`task.console`	Debug logging	Always
`task.ui`	User interaction and notifications	Requires `userInterfaceTools`
`task.guild`	Platform operations (agent search, credentials)	Requires `guildTools`
`task.save()` / `task.restore()`	State persistence	Self-managed state agents only

See the Task object reference for the full API — every method, parameter, and return shape for each service.

Concurrent tool calls

To run the same work over many inputs — or several independent tool calls at once — fan out with task.gather from a single compiled ("use agent") agent. It dispatches every call as one batch and returns the results in source order.

const results = await task.gather(
  input.repos.map((repo) =>
    task.tools.github_repos_get({ owner: input.owner, repo }),
  ),
)

task.gatherSettled is the same fan-out with Promise.allSettled semantics, so one failing call does not sink the rest. Promise.all over tool calls is an anti-pattern in compiled agents: it hides the tool-call promises from the runtime and does not run them in parallel. See Parallel tool calls with task.gather.

Progress logging

Progress logs give users real-time feedback during long-running operations:

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

Next steps

Task object reference

The full API for every service on task.

LLMs

Make language model calls and set provider preferences.

Overview

The Smith

The Factory

Platform

Agent SDK

Tasks and runtime services

Available services

Concurrent tool calls

Progress logging

Next steps

Task object reference

LLMs

​Available services

​Concurrent tool calls

​Progress logging

​Next steps

Task object reference

LLMs

Available services

Concurrent tool calls

Progress logging

Next steps