Skip to main content

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.

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

ServiceDescriptionAvailability
task.toolsTyped proxy for all declared toolsAlways
task.llmLLM calls via generateText()Always
task.envDocker container managementAlways
task.consoleDebug loggingAlways
task.uiUser interaction and notificationsRequires userInterfaceTools
task.guildPlatform operations (agent search, credentials)Requires guildTools
task.save() / task.restore()State persistenceSelf-managed state agents only

​
task.tools — Invoke tools directly

Call any tool in your agent’s tool set by name: 
const pr = await task.tools.github_pulls_get({
  owner: "myorg",
  repo: "myrepo",
  pull_number: 123,
})
Tool names follow the pattern {service}_{operation} — for example, github_issues_get, github_pulls_list, env_create.

​
task.llm — Language model calls

Make LLM calls from your agent. See LLMs for details. 
const result = await task.llm.generateText({
  prompt: "Summarize this text...",
})
// result.text contains the model's response

​
task.env — Docker environments

Create and manage Docker containers for code execution: 
await task.env.create({ baseImage: "node:20" })
const result = await task.env.exec({ command: "npm test" })
await task.env.destroy()

​
task.ui — User interaction

Send messages and prompt users for input. Available when your agent includes userInterfaceTools. 
import { progressLogNotifyEvent } from "@guildai/agents-sdk"

// Send a progress update (non-blocking)
await task.ui?.notify(progressLogNotifyEvent("Processing files..."))

// Ask the user a question (blocks until response)
const response = await task.ui?.prompt({
  type: "text",
  text: "Which language should I use?",
})

​
task.console — Debug logging

task.console.log("Processing item", itemId)

​
task.guild — Platform operations

Search for agents and request credentials. Available when your agent includes guildTools. 
const agents = await task.guild?.search_agent({
  keywords: ["calculator"],
})

await task.guild?.credentials_request({
  service: "linear",
})

​
task.save() / task.restore() — State persistence

Persist and retrieve state between tool calls in a self-managed state agent. State must conform to the agent’s stateSchema. 
await task.save({ step: "fetching", items: [] })

const state = await task.restore() // Returns STATE | undefined
Only available in self-managed state agents — auto-managed state agents handle state automatically via the "use agent" directive.

​
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