Agent - TrueFoundry Docs

Agent Platform is currently in beta. The API may introduce breaking changes.

Overview

An agent is defined by an AgentManifest: its model, system instructions, tools (MCP servers and skills), and runtime configuration. Once created, the agent is saved in the Agent Registry with versioning, RBAC, and audit, and can be invoked by name. There are two ways to create an agent:

Agent Playground - build and test interactively in the UI, then save. See Getting started.
SDK - define the manifest in code and save it programmatically, as shown below.

Once the agent is saved, see Using Agents to start a session and run it.

Creating an Agent

Agent creation uses the standard TrueFoundry client (from truefoundry import client), not the TrueFoundryGateway client used to run agents.

pip install -U truefoundry

The client picks up your credentials from tfy login (or the TFY_API_KEY / TFY_HOST environment variables). Build the manifest and save it to the registry:

Python

from truefoundry import client

{/* TODO: verify the exact agent-creation method name and manifest argument shape against the truefoundry SDK. */}
agent = client.agents.create_or_update(
    manifest={
        "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},
        },
        "instructions": "You are a helpful support assistant that helps customers file issues.",
        "mcp_servers": [
            {
                "name": "zendesk",
                "enable_tools": ["@read-only", "delete_ticket"],
                "require_approval_for_tools": ["@write", "@destructive"],
            }
        ],
        "config": {
            "iteration_limit": 25,
            "sandbox": {"enabled": True},
        },
        "collaborators": [],
    }
)

print(agent.name, agent.version)

The manifest follows the AgentManifest spec. The full YAML form is shown below.

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

Tags and explicit tool names can be combined in the same list.

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"]`.

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

​Overview

​Creating an Agent

​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

Overview

Creating an Agent

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`