Agent SDK is experimental and will have breaking changes!
AgentManifest YAML spec
The YAML below shows a complete agent spec. See AgentManifest for a description of every field.
type: truefoundry-agent
name: support-bot
description: A helpful support assistant
model:
name: anthropic/claude-sonnet-4-6
params:
max_tokens: 4096
temperature: 1.0
reasoning_effort: low
# Instructions are the system prompt for the agent.
instructions: |
You are a helpful support assistant that helps customers file issues.
Current customer is {{customer_name}}. Their support tier is {{support_tier}}.
# Seed messages sent after the system prompt but before `input`.
messages:
- role: user
content: Hello. What can you help me with?
# Variable definitions referenced in `messages` and `instructions`.
variables:
customer_name:
default_value: ""
description: "The name of the customer"
support_tier:
default_value: ""
description: "The support tier of the customer"
# Skills are mounted from the Skills Registry when the agent runs.
skills:
- fqn: agent-skill:truefoundry/skills/web-search:1
preload: true
- fqn: agent-skill:truefoundry/skills/code-interpreter:2
preload: false
mcp_servers:
- name: zendesk
preload: false
enable_tools: ["@read-only", "delete_ticket"]
disable_tools: ["get_users", "list_users"]
preload_tools: ["list_tickets"]
require_approval_for_tools: ["@write", "@destructive", "delete_ticket"]
response_format:
type: text
config:
iteration_limit: 25
timeout_seconds: 900
sandbox:
enabled: true
file_downloads: true
dynamic_sub_agents:
enabled: true
context_management:
compaction:
enabled: true
compaction_threshold_tokens: 60000
large_tool_response:
enabled: true
individual_tool_response_token_threshold: 4000
total_tool_response_token_threshold: 8000
preview_number_of_characters: 500
generative_ui:
enabled: false
ask_user_questions:
enabled: true
collaborators: []
Reference
AgentManifest
AgentManifest is the shape of the spec saved in the Agent Registry. It shares all agent configuration fields below.
Note that variables is a map of objects with default_value and description, not plain string values. Callers can override these with plain string values at invocation time when running the agent.
| Field | Type | Required | Description |
|---|
type | "truefoundry-agent" | Yes | Manifest type discriminator. |
name | string | Yes | Unique identifier for the agent. 3 to 32 lowercase alphanumeric characters; may contain - in between; cannot start with a number. |
description | string | Yes | Human-readable description of what the agent does. Max 2000 characters. |
tags | map<string, string> | No | Key-value tags for the agent. Keys and values are up to 100 characters. |
model | object | Yes | LLM to use. See model. |
skills | array | No | See skills[]. |
mcp_servers | array | No | See mcp_servers[]. |
instructions | string | No | System prompt. Supports {{variable}} placeholders resolved from variables at runtime. |
messages | array | No | Seed messages. See messages[]. |
variables | map<string, VariableDef> | No | Variable definitions. Each entry has optional default_value (string) and description (string). Callers override with plain string values at invocation time. |
sample_inputs | array | No | Example inputs shown on the Agent Chat page. See sample_inputs[]. |
response_format | object | No | See response_format. |
config | object | No | See config. |
collaborators | array | Yes | Users who have access to this agent. |
Agent configuration
The fields below make up the agent configuration shared by the AgentManifest.
model
| Field | Type | Required | Description |
|---|
name | string | Yes | Model identifier in provider/model-name format (e.g. openai-main/gpt-4o, anthropic/claude-sonnet-4-6). |
params | object | No | Model parameters. See model.params. |
model.params
Known parameters are listed below. Any additional provider-specific keys are also accepted.
| Field | Type | Required | Description |
|---|
max_tokens | integer | No | Maximum number of tokens to generate. |
reasoning_effort | string | No | Reasoning depth when supported. One of none, minimal, low, medium, high. |
temperature | float | No | Sampling temperature (0-2). Higher values increase randomness. |
top_p | float | No | Nucleus sampling threshold (0-1). Alternative to temperature. |
top_k | integer | No | Top-K sampling when supported by the provider. |
parallel_tool_calls | boolean | No | Allow the model to request multiple tool calls in parallel when supported. |
messages[]
Seed messages injected after the system prompt and before the user’s input. Only user messages are supported.
| Field | Type | Required | Description |
|---|
role | "user" | Yes | Only user messages are supported. |
content | string | Yes | Text content of the message (non-empty). Supports {{variable}} template placeholders. |
skills[]
Each entry mounts an agent skill from the Skills Registry.
| Field | Type | Required | Description |
|---|
fqn | string | Yes | Fully qualified name of the agent skill, e.g. agent-skill:truefoundry/skills/web-search:1. |
preload | boolean | No | If true, the SKILL.md content is injected into the agent context. Defaults to false. |
mcp_servers[]
Each entry configures an MCP server whose tools are made available to the agent.
Tool selectors support special tags that use MCP tool annotations:
| Tag | Matches |
|---|
@all | Every tool exposed by the server. |
@read-only | Tools with readOnlyHint: true explicitly set. |
@destructive | Tools with destructiveHint: true explicitly set (implies readOnlyHint: false). |
@write | Tools that do not have readOnlyHint: true - including all @destructive tools. @write is a superset of @destructive. |
| Field | Type | Required | Description |
|---|
name | string | Yes | Name of the MCP server as registered in the platform. |
preload | boolean | No | When true (default), this server’s tools are preloaded into context. When false, tools are discovered lazily and only preload_tools stay eager. Defaults to true. |
enable_tools | array of strings | No | Allowlist of tools (or tags) to expose to the agent. Defaults to ["@all"]. |
disable_tools | array of strings | No | Blocklist of tools (or tags) to hide from the agent even if matched by enable_tools. Defaults to []. |
preload_tools | array of strings | No | When preload is false, tools to still preload into context. Defaults to []. |
require_approval_for_tools | array of strings | No | Tools (or tags) that require explicit human approval before the agent can call them. Defaults to ["@write", "@destructive"]. |
Example inputs shown on the Agent Chat page (via “Try Now” on the agent listing). Each entry has:
| Field | Type | Required | Description |
|---|
text | string | No | Example input text for the agent. |
variables | map<string, string> | No | Variable values for the prompt variables defined on the agent. |
| Field | Type | Required | Description |
|---|
type | string | Yes | Output format for the final response. One of text, json_object, or json_schema. |
json_schema | object | No | Required when type is json_schema. Has name (string), optional description, optional schema, and optional strict (boolean). |
config
| Field | Type | Required | Description |
|---|
iteration_limit | integer | No | Maximum number of reasoning iterations (tool call + model response cycles) a turn may perform before it is forced to stop. Between 1 and 1024. |
timeout_seconds | integer | No | Maximum wall-clock time in seconds a turn is allowed to run before it is forcibly terminated. |
sandbox | object | No | Sandboxed code execution settings. See config.sandbox. |
dynamic_sub_agents | object | No | Controls whether the agent can spawn sub-agents dynamically. See config.dynamic_sub_agents. |
context_management | object | No | Controls how the agent manages its context window. See config.context_management. |
generative_ui | object | No | Controls whether the agent can emit generative UI components. See config.generative_ui. |
ask_user_questions | object | No | Controls whether the agent can pause to ask the user clarifying questions. See config.ask_user_questions. |
config.sandbox
| Field | Type | Required | Description |
|---|
enabled | boolean | No | Enable an isolated sandbox environment for code execution. Defaults to false. |
file_downloads | boolean | No | Allow files generated inside the sandbox to be downloaded by the caller. Defaults to false. |
config.dynamic_sub_agents
| Field | Type | Required | Description |
|---|
enabled | boolean | No | Allow the agent to spawn sub-agents dynamically to parallelize or delegate subtasks. Defaults to false. |
config.context_management
| Field | Type | Required | Description |
|---|
compaction | object | No | Automatic context compaction settings. See config.context_management.compaction. |
large_tool_response | object | No | Settings for handling tool responses that exceed token limits. See config.context_management.large_tool_response. |
config.context_management.compaction
| Field | Type | Required | Description |
|---|
enabled | boolean | No | Enable automatic compaction of conversation history when approaching the context limit. Defaults to true. |
compaction_threshold_tokens | integer | No | Token count at which compaction is triggered. |
config.context_management.large_tool_response
| Field | Type | Required | Description |
|---|
enabled | boolean | No | Enable truncation of tool responses that exceed token thresholds. Defaults to true. |
individual_tool_response_token_threshold | integer | No | Token limit for a single tool response before it is truncated. |
total_tool_response_token_threshold | integer | No | Combined token limit across all tool responses in a single iteration before truncation is applied. |
preview_number_of_characters | integer | No | Number of characters to retain as a preview when a tool response is truncated. |
config.generative_ui
| Field | Type | Required | Description |
|---|
enabled | boolean | No | Allow the agent to emit structured UI components (e.g. cards, forms) as part of its response stream. Defaults to false. |
config.ask_user_questions
| Field | Type | Required | Description |
|---|
enabled | boolean | No | Allow the agent to pause mid-run and ask the user a clarifying question before continuing. Defaults to false. |
