Skip to main content

Agents

An agent is a model plus everything it may use, such as a system prompt, tools, sandboxes, workspaces, channels, skills, subagents and hooks. This page covers the model and prompt side. Each capability has its own guide, linked at the end.

broods/index.ts
import { defineAgent, env } from "broods";

export const assistant = defineAgent({
name: "assistant",
description: "General-purpose assistant", // parent agents read this when picking a subagent
provider: { anthropic: { apiKey: env("ANTHROPIC_API_KEY") } },
model: {
provider: "anthropic",
modelId: "claude-sonnet-5",
reasoning: "medium",
},
agent: { system: "You are a concise assistant.", maxTurn: 20 },
publicAccess: true,
});

The full field list is in Configuration.

Model and provider​

provider holds credentials per provider. model.provider picks which one runs. Every Vercel AI SDK provider that ships language models works, plus the OpenRouter, LLM Gateway, Ollama and Cloudflare community providers and any OpenAI-compatible endpoint:

ProviderKeyProviderKey
Alibaba QwenalibabaMiniMaxminimax
AnthropicanthropicMistralmistral
Azure OpenAIazureMoonshot AI Kimimoonshotai
BasetenbasetenOllamaollama
Amazon BedrockbedrockOpenAIopenai
CerebrascerebrasOpenRouteropenrouter
CloudflarecloudflarePerplexityperplexity
CoherecohereTogether.aitogetherai
DeepInfradeepinfraVercel AI Gatewayvercel
DeepSeekdeepseekVercel v0v0
FireworksfireworksGoogle Vertex AIvertex
Google Generative AIgooglexAI Grokxai
GroqgroqZ.ai GLMzai
Hugging FacehuggingfaceOpenAI-compatiblecustom
LLM GatewayllmgatewayChatGPT planchatgpt

Each provider needs an apiKey, except chatgpt, which runs on your ChatGPT plan through a connection (below). Other settings pass straight to that provider's AI SDK factory, so the provider's own docs are the reference. Any setting whose name ends in url, like baseURL or OpenRouter's baseUrl, must be a public https URL. bedrock also takes region, accessKeyId and secretAccessKey. vertex takes project and location and uses express mode, since an API key is required. Service-account credentials do not work. ollama goes to Ollama Cloud unless baseURL points at a public Ollama host.

For a self-hosted or third-party OpenAI-compatible endpoint, use custom:

provider: {
custom: { apiKey: env("LLM_API_KEY"), base_url: "https://llm.example.com/v1" },
},
model: { provider: "custom", modelId: "gpt-oss-120b" },

base_url and baseURL both work. baseUrl fails the sync with an error. For vLLM-style servers, Broods folds several system messages into one and turns cumulative reasoning chunks into increments, so thinking text is not duplicated.

cloudflare takes accountId and a Cloudflare API token as apiKey, and runs Workers AI models. Add gatewayId to send every request through that AI Gateway instead, where modelId names any model the gateway routes:

provider: {
cloudflare: {
accountId: "your-account-id",
gatewayId: "my-gateway",
apiKey: env("CF_AIG_TOKEN"),
headers: { Authorization: env("OPENAI_AUTHORIZATION") }, // optional, "Bearer sk-..."
},
},
model: { provider: "cloudflare", modelId: "openai/gpt-5-mini" },

On the gateway apiKey is sent as cf-aig-authorization. The upstream provider key goes in headers.Authorization, as the whole header value. Leave it out and the gateway uses its stored key or unified billing. Workers AI models keep their @cf/... id and run on the token in apiKey, so that token needs both the AI Gateway Run and Workers AI permissions.

ChatGPT plan​

On a self-hosted deployment, chatgpt runs OpenAI models on your ChatGPT Plus or Pro plan instead of an API key, through Sign in with ChatGPT. Connect it once per account, from the machine with your browser:

broods connect chatgpt

The browser asks you to sign in to ChatGPT and allow plan usage. Your deployment checks the ID token and the grant, keeps the connection, and the CLI prints the model ids your plan can use. Name one in the agent, with no provider.chatgpt entry:

model: { provider: "chatgpt", modelId: "gpt-5.5" },
  • The connection belongs to the account, so every agent in it shares it. Broods refreshes the token before it expires. broods connect lists it, and broods disconnect chatgpt revokes it at OpenAI.
  • Plan usage only takes stateless, streamed Responses requests. Broods sends store: false, sends system prompts as developer messages, and drops temperature, topP, maxOutputTokens and the other settings plan usage refuses. Function tools work. OpenAI's hosted tools (file search, code interpreter, image generation, hosted MCP) do not.
  • Requests count against your ChatGPT plan. Review and limit them at ChatGPT Settings → Usage. When the plan's limit is reached, runs fail until it resets.
  • config.harness does not run on chatgpt.
  • OpenAI offers plan usage to open-source and self-hosted tools. Paid hosted services need OpenAI's approval, so the managed service at gateway.broods.app refuses broods connect chatgpt. Use openai with an API key there.

Reasoning​

One level in model.reasoning works across providers. The levels are provider-default, none, minimal, low, medium, high and xhigh.

Provider-specific settings in model.providerOptions win over reasoning when both are set (not with config.harness, which refuses them), for example providerOptions.openai.reasoningEffort or providerOptions.anthropic.thinking. If a model does not support the level you asked for, the run logs a model.step.warnings event and continues.

Timeouts​

model.timeout is the AI SDK's timeout setting and reaches streamText as you set it. A number is the whole call in milliseconds. The object form takes totalMs (the whole call), stepMs (each step, with its retries and tools), firstChunkMs (from a step's response starting to its first output), chunkMs (between output chunks), toolMs (each tool) and tools for one tool, like { bashMs: 300_000 }. totalMs, stepMs, firstChunkMs and chunkMs end the call when they pass and fail the run, they do not retry it. firstChunkMs starts only once the provider answers, so stepMs is what bounds a request that never gets a response. A tool past its limit is aborted and the model sees the error. Apart from these, Broods fails a run whose model is silent for MODEL_FIRST_CHUNK_TIMEOUT_MS before a call's first output or MODEL_CHUNK_TIMEOUT_MS between outputs (300 s each, set per deployment in operations). Output is text, reasoning, tool input or a file; a stream of keep-alives or errors is silent. That clock includes the wait for a response and pauses while a tool runs, so set the SDK limits below it for them to act first. config.harness ignores model.timeout.

Structured output​

Ask for JSON that matches a schema:

model: {
provider: "google",
modelId: "gemini-3-flash",
output: {
type: "object",
name: "analysis",
schema: {
type: "object",
properties: { summary: { type: "string" }, confidence: { type: "number" } },
required: ["summary", "confidence"],
},
},
},

The run ends with a structured-output stream part that carries the parsed result. client.run returns it as output; client.stream yields it as { type: "structured-output", output }.

System prompt and turn limit​

agent.system is the base prompt. Broods appends a block for each feature that is on, such as workspace guidance, the memory index, available skills, subagents and the scheduler. Every run also gets an <environment> block with the current time. The Tracing tab in the dashboard shows the full assembled prompt for every run.

agent.maxTurn caps model steps per run. The default is 30, and 0 removes the cap. A run that hits the cap ends as failed with its history intact, and continue resumes it. See Conversations.

Session history​

Long conversations are trimmed before each model call. After a turn reaches 500k input tokens (maxContextLength), the stored history is summarized. A turn that fails on context length compacts the history so the next one fits.

session: {
pruning: { enabled: true }, // default on
autoCompaction: { enabled: true, maxContextLength: 500_000 }, // default on, token ceiling
},

Details are in Memory and sessions.

Who can call the agent​

SettingDefaultEffect
publicAccess: trueoffThe runtime key may run this agent. Without it, runtime-key requests get 403 public_access_disabled.
allowRunOverrides: trueoffA runtime-key caller may send system messages and model overrides. Without it, the run gets 403 run_overrides_disabled.
Require user tokenon for new agentsA runtime-key caller must send a signed user token. Without it, the run gets 403 user_token_required. Turn it on or off in the agent's Details tab.

Channels, cron jobs and callers with the account key are never gated by these flags. A private agent is still reachable from Slack.

The user token requirement is not part of the agent config, so broods deploy never changes it. An agent created before it shipped has it off; turn it on once your frontend sends tokens. See Users behind the runtime key.

Harness adapters​

By default an agent runs on the Broods loop, a serverless AI SDK streamText loop with the Broods tools. defineHarness swaps that loop for Claude Code, Codex, Deep Agents, OpenCode or Pi, running inside the agent's first sandbox.

import { defineAgent, defineHarness, defineSandbox, env } from "broods";

export const runner = defineSandbox({
name: "codex-runner",
provider: "sandbox",
persistent: true,
permissionMode: "bypass",
network: { mode: "allow-all" },
onCreate: ["bun install"],
});

export const codingAgent = defineAgent({
name: "coding-agent",
harness: defineHarness({ type: "codex", permissionMode: "allow-all" }),
sandboxes: [runner],
provider: { openai: { apiKey: env("OPENAI_API_KEY") } },
model: { provider: "openai", modelId: "gpt-5.5" },
});
  • The first sandbox must be persistent and use the sandbox or lambda provider.
  • The harness ships its own file tools, so the Broods workspace prompt is off. memory_save still works.
  • Broods MCP servers and account skills still reach the harness. Filter tools with activeTools or inactiveTools on defineHarness.
  • The harness's own "ask the user" tool is off. The agent asks through ask_questions.
  • Steering sent before a turn starts is folded into its prompt. Claude Code, Codex, OpenCode and Pi take steering sent during a turn at its next step. Deep Agents reads it when the next turn starts.
  • Images reach the harness as images, so send them only to a model that reads images. Any other attachment arrives as a note pointing at its copy in the workspace.
  • model.reasoning reaches every harness, and a change applies from the next turn. Pi takes it as its thinking level; provider-default or unset is Pi's medium, also on a session that saved another level. Codex takes it as effort, with minimal as low, and needs a reasoning model; none leaves Codex at its default. Claude Code and Deep Agents take it as effort, with minimal and none as low and xhigh as high, because current Claude models refuse thinking off and older ones refuse xhigh. Claude models without effort (3.x, Sonnet and Haiku 4.5, Opus 4.1, 4.0) get none. OpenCode takes it as the nearest variant for the model and provider route, preferring the higher level on a tie. Direct Anthropic and gateway routes can expose different variants, as can direct OpenAI and gateway routes. none sends none where the model has it and no variant elsewhere; provider-default or unset sends no variant. Whenever a harness runs a level other than the one you set, the run logs a harness.reasoning_changed warning (in broods logs and the dashboard) naming both levels.
  • model.providerOptions and subagent.model.providerOptions are refused with config.harness, in the config and as a per-run override: no harness reads them. Set model.reasoning instead.
  • Policies and structured output are not supported yet.

Each harness supports different model providers, tool approval and tool filtering. The table is in Configuration.

Codex requires permissionMode: "allow-all" and is the only harness with webSearch. The harness's native session is checkpointed after each turn, so the next request continues the same session.

What to add next​