Create an agent

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

tfy login --host <your-control-plane-url>

The client picks up credentials from tfy login or the TFY_API_KEY / TFY_HOST environment variables. For more details, see the CLI setup guide.

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": [
            {
                "type": "truefoundry-mcp-registry",
                "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

Section	Purpose
`model`	Which LLM to use (via AI Gateway) and sampling parameters.
`instructions`	System 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.
`config`	Runtime limits: iteration count, timeout, sandbox, sub-agents, compaction.
`collaborators`	Users 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:
  - 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: []

MCP tool selectors

MCP server entries support special tags that match MCP tool annotations:

Tag	Matches
`@all`	Every tool exposed by the server.
`@read-only`	Tools with `readOnlyHint: true`.
`@destructive`	Tools with `destructiveHint: true`.
`@write`	Tools 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.

Agent Harness

Agent Governance

Install and authenticate

Save an agent to the registry

What goes in a manifest

Full YAML example

MCP tool selectors

Next step

​Install and authenticate

​Save an agent to the registry

​What goes in a manifest

​Full YAML example

​MCP tool selectors

​Next step

Install and authenticate

Save an agent to the registry

What goes in a manifest

Full YAML example

MCP tool selectors

Next step