Tasks

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, Docker environments, 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`	Docker container management	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.

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..."))
await task.env.create({ baseImage: "node:20" })

await task.ui?.notify(progressLogNotifyEvent("Running tests..."))
const result = await task.env.exec({ command: "npm test" })

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

Platform

Insights

Agent SDK

Available services

Progress logging

Next steps

Task object reference

LLMs

​Available services

​Progress logging

​Next steps

Task object reference

LLMs

Available services

Progress logging

Next steps