Skip to main content
For a guided walkthrough, see Create an agent.

​
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.
FieldTypeRequiredDescription
type"truefoundry-agent"YesManifest type discriminator.
namestringYesUnique identifier for the agent. 3 to 32 lowercase alphanumeric characters; may contain - in between; cannot start with a number.
descriptionstringYesHuman-readable description of what the agent does. Max 2000 characters.
tagsmap<string, string>NoKey-value tags for the agent. Keys and values are up to 100 characters.
modelobjectYesLLM to use. See model.
skillsarrayNoSee skills[].
mcp_serversarrayNoSee mcp_servers[].
instructionsstringNoSystem prompt. Supports {{variable}} placeholders resolved from variables at runtime.
messagesarrayNoSeed messages. See messages[].
variablesmap<string, VariableDef>NoVariable definitions. Each entry has optional default_value (string) and description (string). Callers override with plain string values at invocation time.
sample_inputsarrayNoExample inputs shown on the Agent Chat page. See sample_inputs[].
response_formatobjectNoSee response_format.
configobjectNoSee config.
collaboratorsarrayYesUsers who have access to this agent.

​
Agent configuration

The fields below make up the agent configuration shared by the AgentManifest.

​
model

FieldTypeRequiredDescription
namestringYesModel identifier in provider/model-name format (e.g. openai-main/gpt-4o, anthropic/claude-sonnet-4-6).
paramsobjectNoModel parameters. See model.params.

​
model.params

Known parameters are listed below. Any additional provider-specific keys are also accepted.
FieldTypeRequiredDescription
max_tokensintegerNoMaximum number of tokens to generate.
reasoning_effortstringNoReasoning depth when supported. One of none, minimal, low, medium, high.
temperaturefloatNoSampling temperature (0-2). Higher values increase randomness.
top_pfloatNoNucleus sampling threshold (0-1). Alternative to temperature.
top_kintegerNoTop-K sampling when supported by the provider.
parallel_tool_callsbooleanNoAllow 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.
FieldTypeRequiredDescription
role"user"YesOnly user messages are supported.
contentstringYesText content of the message (non-empty). Supports {{variable}} template placeholders.

​
skills[]

Each entry mounts an agent skill from the Skills Registry.
FieldTypeRequiredDescription
fqnstringYesFully qualified name of the agent skill, e.g. agent-skill:truefoundry/skills/web-search:1.
preloadbooleanNoIf 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:
TagMatches
@allEvery tool exposed by the server.
@read-onlyTools with readOnlyHint: true explicitly set.
@destructiveTools with destructiveHint: true explicitly set (implies readOnlyHint: false).
@writeTools that do not have readOnlyHint: true - including all @destructive tools. @write is a superset of @destructive.
Tags and explicit tool names can be combined in the same list.
FieldTypeRequiredDescription
namestringYesName of the MCP server as registered in the platform.
preloadbooleanNoWhen 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_toolsarray of stringsNoAllowlist of tools (or tags) to expose to the agent. Defaults to ["@all"].
disable_toolsarray of stringsNoBlocklist of tools (or tags) to hide from the agent even if matched by enable_tools. Defaults to [].
preload_toolsarray of stringsNoWhen preload is false, tools to still preload into context. Defaults to [].
require_approval_for_toolsarray of stringsNoTools (or tags) that require explicit human approval before the agent can call them. Defaults to ["@write", "@destructive"].

​
sample_inputs[]

Example inputs shown on the Agent Chat page (via “Try Now” on the agent listing). Each entry has:
FieldTypeRequiredDescription
textstringNoExample input text for the agent.
variablesmap<string, string>NoVariable values for the prompt variables defined on the agent.

​
response_format

FieldTypeRequiredDescription
typestringYesOutput format for the final response. One of text, json_object, or json_schema.
json_schemaobjectNoRequired when type is json_schema. Has name (string), optional description, optional schema, and optional strict (boolean).

​
config

FieldTypeRequiredDescription
iteration_limitintegerNoMaximum number of reasoning iterations (tool call + model response cycles) a turn may perform before it is forced to stop. Between 1 and 1024.
timeout_secondsintegerNoMaximum wall-clock time in seconds a turn is allowed to run before it is forcibly terminated.
sandboxobjectNoSandboxed code execution settings. See config.sandbox.
dynamic_sub_agentsobjectNoControls whether the agent can spawn sub-agents dynamically. See config.dynamic_sub_agents.
context_managementobjectNoControls how the agent manages its context window. See config.context_management.
generative_uiobjectNoControls whether the agent can emit generative UI components. See config.generative_ui.
ask_user_questionsobjectNoControls whether the agent can pause to ask the user clarifying questions. See config.ask_user_questions.

​
config.sandbox

FieldTypeRequiredDescription
enabledbooleanNoEnable an isolated sandbox environment for code execution. Defaults to false.
file_downloadsbooleanNoAllow files generated inside the sandbox to be downloaded by the caller. Defaults to false.

​
config.dynamic_sub_agents

FieldTypeRequiredDescription
enabledbooleanNoAllow the agent to spawn sub-agents dynamically to parallelize or delegate subtasks. Defaults to false.

​
config.context_management

FieldTypeRequiredDescription
compactionobjectNoAutomatic context compaction settings. See config.context_management.compaction.
large_tool_responseobjectNoSettings for handling tool responses that exceed token limits. See config.context_management.large_tool_response.

​
config.context_management.compaction

FieldTypeRequiredDescription
enabledbooleanNoEnable automatic compaction of conversation history when approaching the context limit. Defaults to true.
compaction_threshold_tokensintegerNoToken count at which compaction is triggered.

​
config.context_management.large_tool_response

FieldTypeRequiredDescription
enabledbooleanNoEnable truncation of tool responses that exceed token thresholds. Defaults to true.
individual_tool_response_token_thresholdintegerNoToken limit for a single tool response before it is truncated.
total_tool_response_token_thresholdintegerNoCombined token limit across all tool responses in a single iteration before truncation is applied.
preview_number_of_charactersintegerNoNumber of characters to retain as a preview when a tool response is truncated.

​
config.generative_ui

FieldTypeRequiredDescription
enabledbooleanNoAllow the agent to emit structured UI components (e.g. cards, forms) as part of its response stream. Defaults to false.

​
config.ask_user_questions

FieldTypeRequiredDescription
enabledbooleanNoAllow the agent to pause mid-run and ask the user a clarifying question before continuing. Defaults to false.