> ## Documentation Index
> Fetch the complete documentation index at: https://www.truefoundry.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create an agent

> Define an AgentManifest and save a TrueFoundry agent to the Agent Registry using the truefoundry Python SDK.

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](/docs/agent-platform/agent-harness/getting-started)** — 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](/docs/agent-platform/agent-harness/sdk/use-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.

<CodeGroup>
  ```bash Install theme={"dark"}
  pip install -U truefoundry
  ```

  ```bash Login theme={"dark"}
  tfy login --host <your-control-plane-url>
  ```
</CodeGroup>

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](/docs/setup-cli).

## Save an agent to the registry

Build a manifest and call `create_or_update`:

```python Python theme={"dark"}
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`](/docs/agent-platform/agent-harness/sdk/agent-manifest-reference) 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 `[]`).                   |

<Tip>
  Start with a minimal manifest (model + instructions + collaborators) and add MCP servers, skills, and config as you need them. See [MCP servers](/docs/agent-platform/agent-harness/mcp-servers) and [Skills](/docs/agent-platform/agent-harness/skills) for platform concepts.
</Tip>

## Full YAML example

The YAML below shows every commonly used field. See the [Agent manifest reference](/docs/agent-platform/agent-harness/sdk/agent-manifest-reference) for complete field descriptions.

```yaml theme={"dark"}
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](https://modelcontextprotocol.io/specification/2025-11-25/schema#toolannotations):

| 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](/docs/agent-platform/agent-harness/human-in-the-loop) for how approvals work at runtime.

## Next step

Your agent is saved in the Registry. Continue to [Use an agent](/docs/agent-platform/agent-harness/sdk/use-agent) to open a session and invoke it.