Agent SDK

The @guildai/agents-sdk package provides types, utilities, tool sets, and platform service interfaces for building Guild agents. An agent takes typed input, does its work using tools, LLMs, or other agents, and returns typed output.

The current release is @guildai/agents-sdk 0.6.0, a breaking change that requires Zod ~4.3.0 (4.3.x) rather than any Zod 4.x release. See Version and Zod requirement for details.

Agent types

Not every agent needs the SDK. Start with the type that matches the work:

Native agents

A prompt and a tool list. No code, no container — the shortest path to a running agent, and the one to try first.

TypeScript LLM agents

The TypeScript form of the same idea: a system prompt plus tools, with attachments, a custom input schema, and per-agent model preferences available.

Auto-managed state agents

A TypeScript function that runs to completion. Deterministic, cost-predictable, and suitable for algorithmic tasks.

Self-managed state agents

An event-driven agent for parallel tool calls and fine-grained state control.

Goose agents

An agent defined by a recipe.yaml file in the Goose recipe format. No TypeScript required.

OpenClaw agents

Markdown instructions and skills, with a coding toolchain built in. No TypeScript required.

Native, Goose, and OpenClaw agents are written in Markdown and YAML and do not use this SDK, so most of what follows applies to TypeScript agents only. See Agent types for a full overview of the four execution architectures.

Choosing an agent type

Agent type	Written in	Ease	Control	LLM cost	Best for
Native	Markdown prompt	Easiest	Stochastic	Variable	A prompt + tools, text in and text out
TypeScript LLM	TypeScript	Easy	Stochastic	Variable	A prompt + tools that needs attachments, typed input, or model preferences
Auto-managed state	TypeScript	Moderate	Deterministic	Fixed	Algorithmic workflows
Self-managed state	TypeScript	Challenging	Deterministic	Fixed	Parallel tool calls, complex state
Goose	YAML recipe	Easy	Stochastic	Variable	Declared parameters and a response schema; file, shell, and repository work
OpenClaw	Markdown workspace	Easy	Stochastic	Variable	Written instructions and skills; file, shell, and repository work

Agent type identifiers

Every agent has a mandatory agent_type property that identifies how it is implemented. The platform sets this value automatically and exposes it in the API.

`agent_type`	Description
`'GUILD_NATIVE'`	A Native agent: `PROMPT.md` plus an optional `guild.yaml`.
`'GUILD_TYPESCRIPT'`	A TypeScript agent, whether built with `llmAgent` or with the `agent` function (auto-managed or self-managed state).
`'GOOSE'`	A Goose agent.
`'OPENCLAW'`	An OpenClaw agent.

Agent schema

Every agent declares:

description — (optional, deprecated as of @guildai/agents-sdk 0.4.0) Guild generates the agent’s published description automatically from its code, so setting description in code no longer affects the published description.
inputSchema — A Zod schema describing the agent’s input.
outputSchema — A Zod schema describing the agent’s output.
tools — (optional) Tools the agent may use.

inputSchema must be z.object({ ... }) at the root. The runtime registers each agent as an LLM tool, and LLM providers require "type": "object" at the top of tool input schemas. Root schemas that are not objects — such as z.discriminatedUnion(), z.union(), z.record(), or a primitive like z.string() — are rejected and fail the build. Wrap a non-object schema in a root z.object() property instead: use z.object({ data: z.record(z.string(), z.number()) }) rather than z.record(z.string(), z.number()).

The runtime only supports @guildai/agents-sdk and zod. You cannot import external npm packages or Node.js built-in modules — agents run in a sandboxed environment.

Network isolation

Agents have no direct route to the internet. An agent’s container can reach the Guild API and nothing else, so every outbound request — LLM calls, tool calls, and anything else — travels through Guild. The practical consequence is that direct HTTP clients do not work. fetch exists but cannot connect, and axios and node:http cannot be imported in the first place:

// Fails: there is no route from the agent container to api.example.com.
const res = await fetch("https://api.example.com/data")

// Fails earlier still — the runtime only resolves @guildai/agents-sdk and zod.
import axios from "axios"
import http from "node:http"

To reach an external service, call an integration through task.tools. Guild proxies the request, attaches the workspace’s credentials, and returns a typed result:

const pr = await task.tools.github_pulls_get({
  owner: "guildaidev",
  repo: "guildcode",
  pull_number: 42,
})

Fetching an arbitrary URL

For a URL no integration covers, Guild publishes a general-purpose HTTP integration, guildai~experimental-fetch. Import its tool set and pick the experimental_fetch_fetch tool:

import { pick } from "@guildai/agents-sdk"
import { ExperimentalFetchTools } from "@guildai-services/guildai~experimental-fetch"

export default llmAgent({
  tools: {
    ...pick(ExperimentalFetchTools, ["experimental_fetch_fetch"]),
  },
  systemPrompt,
})

The tool takes url and method (GET, POST, PUT, DELETE, or PATCH), plus optional data, headers, follow_redirects (default true), verify_certificate (default true), timeout_seconds (default 5), and max_bytes to cap the response body so a large page cannot overflow the agent’s context. A response comes back as status_code, the final url, headers, and a body — parsed under json when the content type is application/json, otherwise as text. max_bytes caps the text body only, counting UTF-8 bytes: an oversized body is cut to the limit and given a trailing [Response truncated to <max_bytes> bytes] marker, while a JSON response is returned intact whatever the limit. Omit max_bytes and the full body comes back. The tool set also carries experimental_fetch_fetch_async, which takes the same parameters but returns its result through a hook. The runtime suspends the agent and resumes it when the request completes, instead of holding the call open for the duration. It sends no credentials, so use it for public URLs. For a service you call repeatedly, or one needing authentication, create an integration instead and let Guild manage the credentials and schemas.

This applies to every line of agent code, including inside custom tools built with guildServiceTool or guildAgentTool. A fetch call inside a custom tool fails exactly as an inline one does.

Next steps

Native agents

Build an agent from a prompt and a tool list, with no code.

TypeScript LLM agents

Build prompt-driven agents with tools, in TypeScript.

Auto-managed state agents

Build deterministic TypeScript agents.

Self-managed state agents

Build event-driven agents with explicit state control.

Goose agents

Build agents from a Goose recipe, with no TypeScript.

OpenClaw agents

Build agents from Markdown instructions and skills.

Tasks

Access LLMs, workspace variables, and platform services at runtime.

Overview

The Smith

The Factory

Platform

Insights

Agent SDK

Agent types

Native agents

TypeScript LLM agents

Auto-managed state agents

Self-managed state agents

Goose agents

OpenClaw agents

Choosing an agent type

Agent type identifiers

Agent schema

Network isolation

Fetching an arbitrary URL

Next steps

Native agents

TypeScript LLM agents

Auto-managed state agents

Self-managed state agents

Goose agents

OpenClaw agents

Tasks

​Agent types

Native agents

TypeScript LLM agents

Auto-managed state agents

Self-managed state agents

Goose agents

OpenClaw agents

​Choosing an agent type

​Agent type identifiers

​Agent schema

​Network isolation

​Fetching an arbitrary URL

​Next steps

Native agents

TypeScript LLM agents

Auto-managed state agents

Self-managed state agents

Goose agents

OpenClaw agents

Tasks

Agent types

Choosing an agent type

Agent type identifiers

Agent schema

Network isolation

Fetching an arbitrary URL

Next steps