Skip to main content
Agent SDK is experimental and will have breaking changes!
An agent is a saved definition in the Agent Registry: its model, system instructions, tools (MCP servers and skills), and runtime configuration. Once saved, any application can invoke it by name. There are two ways to create an agent:
  • Agent Playground — build and test interactively in the UI, then save.
  • SDK — define the manifest in code and save it programmatically, as shown below.
After saving, continue to Use an agent to open a session and invoke it.

​
Install and authenticate

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 credentials from tfy login or the TFY_API_KEY / TFY_HOST environment variables.

​
Save an agent to the registry

Build a manifest and call create_or_update:
Python
from truefoundry import client

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 registry handles versioning, RBAC, and audit automatically.

​
What goes in a manifest

SectionPurpose
modelWhich LLM to use (via AI Gateway) and sampling parameters.
instructionsSystem prompt. Supports {{variable}} placeholders from variables.
mcp_servers[]MCP tools the agent can call, with allowlists and approval gates.
skills[]Versioned skills from the Skills Registry, optionally preloaded.
configRuntime limits: iteration count, timeout, sandbox, sub-agents, compaction.
collaboratorsUsers with access to this agent (required, can be []).
Start with a minimal manifest (model + instructions + collaborators) and add MCP servers, skills, and config as you need them. See MCP servers and Skills for platform concepts.

​
Full YAML example

The YAML below shows every commonly used field. See the Agent manifest reference for complete field descriptions. 
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 user 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: []

​
MCP tool selectors

MCP server entries support special tags that match MCP tool annotations:
TagMatches
@allEvery tool exposed by the server.
@read-onlyTools with readOnlyHint: true.
@destructiveTools with destructiveHint: true.
@writeTools that do not have readOnlyHint: true — a superset of @destructive.
Use enable_tools to allowlist, disable_tools to blocklist, and require_approval_for_tools to gate sensitive calls. See Human in the loop for how approvals work at runtime.

​
Next step

Your agent is saved in the Registry. Continue to Use an agent to open a session and invoke it.