Agent manifest reference

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:
  - type: user.message
    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:
  - type: truefoundry-skills-registry
    fqn: agent-skill:truefoundry/skills/web-search:1
    preload: true
  - type: truefoundry-skills-registry
    fqn: agent-skill:truefoundry/skills/code-interpreter:2
    preload: false
mcp_servers:
  - type: truefoundry-mcp-registry
    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: true
  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. These are definition-time seed messages on the manifest — distinct from runtime UserMessage turn input, though both use type: "user.message".

Field	Type	Required	Description
`type`	`"user.message"`	Yes	Message type discriminator.
`content`	string	Yes	Text content of the message (non-empty). Supports `{{variable}}` template placeholders.

`skills[]`

Each entry is a discriminated union. Use type to select the variant. Registered skill (type: "truefoundry-skills-registry")

Field	Type	Required	Description
`type`	`"truefoundry-skills-registry"`	Yes	Skill source discriminator.
`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 is a discriminated union. Use type to select the variant. 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`.

Tags and explicit tool names can be combined in the same list. Shared tool fields (both variants):

Field	Type	Required	Description
`preload`	boolean	No	When `true`, this server’s tools are preloaded into context. When `false` (default), tools are discovered lazily and only `preload_tools` stay eager.
`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"]`.

Registered MCP server (type: "truefoundry-mcp-registry")

Field	Type	Required	Description
`type`	`"truefoundry-mcp-registry"`	Yes	MCP server source discriminator.
`name`	string	Yes	Name of the MCP server as registered in the platform.

`sample_inputs[]`

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.

`response_format`

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 `true`.
`file_downloads`	boolean	No	Allow files generated inside the sandbox to be downloaded by the caller. Defaults to `true`.

`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 `true`.

`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 `true`.

`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 `true`.

Agent Harness

Agent Governance

AgentManifest YAML spec

Reference

AgentManifest

Agent configuration

`model`

`model.params`

`messages[]`

`skills[]`

`mcp_servers[]`

`sample_inputs[]`

`response_format`

`config`

`config.sandbox`

`config.dynamic_sub_agents`

`config.context_management`

`config.context_management.compaction`

`config.context_management.large_tool_response`

`config.generative_ui`

`config.ask_user_questions`

​AgentManifest YAML spec

​Reference

​AgentManifest

​Agent configuration

​model

​model.params

​messages[]

​skills[]

​mcp_servers[]

​sample_inputs[]

​response_format

​config

​config.sandbox

​config.dynamic_sub_agents

​config.context_management

​config.context_management.compaction

​config.context_management.large_tool_response

​config.generative_ui

​config.ask_user_questions

AgentManifest YAML spec

Reference

AgentManifest

Agent configuration

`model`

`model.params`

`messages[]`

`skills[]`

`mcp_servers[]`

`sample_inputs[]`

`response_format`

`config`

`config.sandbox`

`config.dynamic_sub_agents`

`config.context_management`

`config.context_management.compaction`

`config.context_management.large_tool_response`

`config.generative_ui`

`config.ask_user_questions`