Skip to main content
An agent is a saved, reusable definition: a model, instructions, the tools and skills it can use, and a set of runtime behaviors. You build one on the Build Agent page or via the SDK — either way, TrueForge stores the same agent spec, and any number of conversations can run against it.

What’s in an agent

Each option below is part of the agent definition. The Set in line on each shows where you can configure it today — the chat UI, the API, or both.
The LLM that runs the agent loop. Pick any model from the providers you configured under Settings → Models; switching later is a one-click change, with no new API keys in the agent definition.Via the API you can also pass model parameters — temperature, max_tokens, top_p, top_k, reasoning_effort, and more — which are forwarded to the provider as-is.Set in: UI (which model) · API (model + parameters)
The system prompt for this agent’s role — what it does, who it’s for, and how it should behave. The harness appends its own guidance for enabled capabilities (sandbox, subagents, and so on), so keep this focused on your agent and move long playbooks into skills instead of the prompt.Set in: UI + API
The MCP servers whose tools the agent can call, attached by name from Settings → Connectors. Credentials live in the connector, never in the agent. Prefer only the servers the agent actually needs.Per server you can further control:
  • Which tools are enabled or disabled — expose everything, only read-only tools, or a specific list. Choose these in Select MCP Tools when you attach the server, or via the API.
  • Preload — load a server’s full tool definitions upfront, or (default) discover them on demand to keep context lean. See Deferred Tool Loading. Toggle it on the connector’s chip in Build Agent, or via the API.
  • Tool approval — pause before sensitive tool calls until a human approves. See below.
Set in: UI + API
Some tool calls shouldn’t run without a human’s sign-off. Tool approval pauses the agent before such a call, shows the tool name and arguments, and resumes only after the user chooses Allow or Deny in the chat UI.By default, the agent asks for approval before tools the MCP server marks as write or destructive (require_approval_for_tools defaults to ["@write", "@destructive"]). Read-only tools run on their own.
@write and @destructive only match tools the MCP server has labeled. Many servers skip labels, so those tools run without asking — even if they change data. To pause on a specific tool anyway, list it by name, or set require_approval_for_tools to ["@all"].
Chat UI pausing on a tool call, showing the request payload with Allow and Deny buttons

The chat UI pauses on a sensitive tool call with Allow / Deny.

You can override which tools require approval per MCP server. In Select MCP Tools, the shield next to an enabled tool toggles approval for it, and the Other Actions / Destructive Actions headers each have an Approval required switch for that group; via the API, set require_approval_for_tools to @all, @write, @destructive, or literal tool names.
The Select MCP Tools dialog with a shielded web_search tool and a Selected Tools panel listing tools with approval badges

The shield on an enabled tool row toggles approval; the Selected Tools panel counts how many are gated.

To review what a saved agent ended up with, open its Overview tab: MCP Servers & Tools lists each attached server with how many of its tools need approval, and expanding one shows every tool with its read / write / destructive label and shield state.
The agent Overview tab showing an MCP Servers and Tools panel with per-server approval counts and a tool list labelled read or write

The agent Overview tab, with the slack server expanded to show each tool's annotation and shield state.

Set in: UI + API
Skills are git-backed SKILL.md instruction packs that teach the agent specialized procedures — querying a database, following an escalation playbook, drafting release notes. Attach them by name; the agent loads the full skill only when it decides the skill is relevant.Attaching skills requires the agent’s sandbox to be enabled.Set in: UI + API
An isolated environment for running code, files, and shell commands, separate from the server. It’s off by default and provisioned only when the agent needs it. Required for skills and Code Mode.Optional extra: allow clients to download files the agent produces.Set in: UI (on/off + file downloads) · API (same)
Lets the agent stream interactive components — charts, tables, cards, forms — that the chat UI renders as React. The agent embeds a small OpenUI snippet in its response; the client renders real, registered components as tokens stream in (no arbitrary code execution). On by default.
Rendered Generative UI response with an inline bar chart of the world's most spoken languages

A Generative UI response with a chart rendered inline in chat.

Skip it for short explanations, bullet lists, or code where markdown is enough.Set in: UI + API
Lets the agent pause at a decision it shouldn’t guess — which environment to deploy to, which of several matches the user meant, an ambiguous required field — show a multiple-choice prompt, and resume with the chosen answer. On by default.
Chat UI showing an agent question with multiple-choice options and a Submit button

The chat UI renders the question and options as a selectable card.

Good for disambiguating matches, filling required fields the user didn’t specify, or picking a strategy before a destructive step. Skip it when the agent can confidently infer the answer — over-asking turns the agent into a form.Set in: UI + API
Enable the harness to spawn subagents. This lets the TrueForge harness solve complicated tasks by breaking them into smaller pieces and running them in parallel, then merging only their results — keeping the main agent’s context clean. On by default. See Subagents for how it works.
Chat UI showing three parallel subagents (notion-research, obsidian-research, evernote-research) under the Agent steps panel

The agent fans out to parallel subagents, each shown as its own trace under Agent steps.

Set in: UI + API
Keeps long runs efficient. Compaction summarizes older history once the context crosses a token threshold, and large tool-response offloading writes oversized tool outputs to a sandbox file and leaves a short preview in context. Both are on by default, with the compaction threshold and both toggles in Runtime Config. See Harness Capabilities and Large tool responses.Set in: UI + API
A safety stop for how many agent-loop steps a single turn can take (1–1024, default 100). It halts runaway loops; it isn’t a normal quality lever. Set it in Runtime Config.Set in: UI + API
Constrains the agent’s final output. The default is free-form text; you can require a JSON object, or a JSON value matching a schema you provide.Set in: API
Optional starter messages added to the top of every new conversation with this agent, before the user says anything. Use them to prime the agent each time — for example, an opening line it should greet with, or standing context every session should begin from. They apply at the start of each session, not just once.Set in: API

Create an agent via the UI

Open Build Agent from the sidebar. The Agent Config panel on the left is where you assemble the agent; the chat on the right lets you test it as you go.
  1. Select a model from the providers you configured under Settings → Models, and set its reasoning effort.
  2. Write focused instructions — role, audience, and behavior.
  3. Add MCP servers — open Select MCP Tools, pick the servers the agent should use, and choose which of their tools to enable. Use the shield on a tool to require approval before it runs — destructive tools are gated by default. Set a server’s preload toggle on its chip to load its tools upfront.
  4. Add skills if the agent should follow specialized procedures (requires sandbox enabled).
  5. Open Runtime Config to review execution and context behavior — Dynamic sub-agents, Generative UI, Ask user questions, the sandbox, iteration limit, and context compaction (all on by default).
  6. Click Save Agent, give it a name and description, and save. It then appears under Agents.
The Save agent dialog with an agent name and a description field

Save a reusable agent from the Build Agent page.

Available in the UI today: model, instructions, MCP servers (attach, tool selection, tool approval, preload), skills, sandbox (on/off and file downloads), iteration limit, context compaction, and the Dynamic sub-agents, Generative UI, and Ask user questions toggles.
A few options are still API only: model parameters (temperature, top_p, and so on), response format, and seed messages. See Create an agent via the API.

Create an agent via the API

The SDK and HTTP API expose every option through the agent spec. You either save the spec as a named, reusable agent and reference it by name, or pass it inline when you open a session. All fields are snake_case, and every field except model has a default.

Save and run an agent

1

Connect the client

When OIDC login is on, pass an ID token; see Get a token and connect. When login is off, omit token.
2

Save the spec as a named agent

agents.create (POST /api/v1/agents) stores the spec under a unique name and returns the agent with its server-generated id. The name is immutable and must be unique — a duplicate returns 409. description is required.
3

Open a session and run turns

Reference the saved agent by name, then stream a turn. See Use an agent for the full loop, including approvals and questions.
Skip saving — pass the spec inline when you create the session, and nothing is persisted to the registry:
Manage saved agents with the rest of the agents methods:

The full agent spec

The manifest you save (or the inline spec) is the agent spec below — every field, with defaults.
The Set via column on each table below marks where a field is configurable today — UI, API, or both.

model

The only required field. model.params recognizes max_tokens, temperature, top_p, top_k, parallel_tool_calls (boolean), and reasoning_effort (string). Extra keys are allowed and forwarded to the provider as-is.

instructions

Set via: UI + API Optional string. The agent’s system prompt — its role, behavior, and constraints.

mcp_servers

Optional array. Each entry attaches a configured MCP server by name: @read-only, @write, and @destructive follow the labels the MCP server puts on each tool. Unlabeled tools (and tools marked read-only) are not covered by @write / @destructive, so they run without an approval pause. Gate them by name, or use @all.

skills

Set via: UI + API Optional array of name-only references to configured skills:
Skill names may contain letters, numbers, ., _, and - (max 64 characters). Attaching skills requires config.sandbox.enabled: true.

config

Runtime behavior. Every field has a default, so config can be omitted entirely.

config.sandbox

config.context_management

Compaction is enabled by default. When its trigger is omitted, it runs at 80% of the configured model’s context length, or at 50,000 input tokens when that context length is unavailable.

response_format

Set via: API Optional. Constrains the agent’s final output: { "type": "text" } (default), { "type": "json_object" }, or { "type": "json_schema", "json_schema": { ... } }.

messages

Set via: API Optional array of seed messages injected at the start of every session: