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

# Agent Syntax Reference

> Complete syntax guide for AgentUse agent files

## File Format

AgentUse agents are markdown files with YAML frontmatter for configuration and plain English instructions.

```markdown theme={"system"}
---
# YAML configuration
name: agent-name
model: provider:model
---

# Markdown content (system prompt)
You are an AI assistant.

## Optional sections
Additional instructions or context.
```

## Frontmatter Reference

### Required Fields

<ParamField path="model" type="string" required>
  AI model to use for the agent.

  Format: `provider:model-name`

  Supported providers:

  * `anthropic` - Anthropic Claude models
  * `openai` - OpenAI GPT models
  * `openrouter` - OpenRouter models
  * `opencode-go` - OpenCode Go open coding models
  * `bedrock` - Amazon Bedrock (Claude, Llama, Mistral, Nova, etc.)

  ```yaml theme={"system"}
  model: anthropic:claude-sonnet-5
  model: openai:gpt-5.4-mini
  model: openrouter:z-ai/glm-5.2
  model: opencode-go:kimi-k2.7-code
  model: bedrock:us.anthropic.claude-sonnet-4-5-20250929-v1:0
  ```

  You can also specify a custom environment variable suffix:

  ```yaml theme={"system"}
  model: anthropic:claude-sonnet-5:dev  # Uses ANTHROPIC_API_KEY_DEV
  model: opencode-go:kimi-k2.7-code:dev   # Uses OPENCODE_GO_API_KEY_DEV
  ```
</ParamField>

### Optional Fields

<ParamField path="timeout" type="number" required={false}>
  Maximum execution time in seconds before the agent is terminated.
  Default: 300 (5 minutes)

  This prevents runaway agents and provides a safety ceiling for execution time.

  **Precedence:** CLI `--timeout` flag overrides this value.

  ```yaml theme={"system"}
  timeout: 600  # 10 minutes
  timeout: 1800  # 30 minutes
  ```

  <Note>
    Choose a timeout appropriate for your agent's expected workload. Simple tasks may complete in seconds, while complex multi-step workflows may need 10-30 minutes.
  </Note>
</ParamField>

<ParamField path="maxSteps" type="number" required={false}>
  Maximum number of LLM generation steps (tool call cycles) the agent can take.
  Default: 100

  This prevents infinite loops and controls cost by limiting the number of LLM calls.

  **Precedence:** `MAX_STEPS` environment variable overrides this value.

  ```yaml theme={"system"}
  maxSteps: 50   # Conservative limit for simple tasks
  maxSteps: 200  # Higher limit for complex workflows
  ```

  <Warning>
    Each step typically involves an LLM call. Higher values increase potential cost if the agent gets stuck in a loop.
  </Warning>
</ParamField>

<ParamField path="description" type="string" required={false}>
  A brief description of what the agent does.

  This description is used in multiple contexts:

  * **As subagent tool description**: When this agent is used as a subagent, this becomes the tool description that parent agents see
  * **CLI output**: Displayed when running the agent to provide context
  * **Plugin events**: Available to plugins for logging or monitoring
  * **Documentation**: Self-documenting agents for teams

  Best practices:

  * Keep it concise (80-120 characters recommended)
  * Be action-oriented (describe what the agent does, not what it is)
  * Focus on the primary capability or purpose

  ```yaml theme={"system"}
  description: "Reviews code for security vulnerabilities and best practices"
  description: "Generates unit tests for JavaScript/TypeScript functions"
  description: "Analyzes logs and identifies potential issues"
  ```
</ParamField>

<ParamField path="version" type="string" required={false}>
  Version identifier for the agent. For developer documentation only - not displayed or used at runtime.

  ```yaml theme={"system"}
  version: "1.0.0"
  version: "2024-01-15"
  ```
</ParamField>

<ParamField path="notes" type="string" required={false}>
  Developer notes for setup instructions, requirements, or other documentation. Not displayed at runtime.

  ```yaml theme={"system"}
  notes: |
    Setup:
    1. Set NEWS_API_KEY environment variable
    2. Install jq: brew install jq
  ```
</ParamField>

<ParamField path="mcpServers" type="object" required={false}>
  Configuration for Model Context Protocol (MCP) servers that provide tools and resources to the agent.

  Each server is defined as a key-value pair where the key is the server name and the value is the server configuration.
</ParamField>

<ParamField path="subagents" type="array" required={false}>
  Array of sub-agent configurations that this agent can delegate tasks to.

  Each sub-agent must specify a `path` to the `.agentuse` file, with optional `name` and `maxSteps` parameters.

  **Path Resolution**: Subagent paths are resolved relative to the **parent agent file's directory**, not the current working directory. This ensures portability and consistency.

  ```yaml theme={"system"}
  # In /project/agents/main.agentuse
  subagents:
    - path: ../utils/helper.agentuse  # Resolves to /project/utils/helper.agentuse
    - path: ./local-agent.agentuse    # Resolves to /project/agents/local-agent.agentuse
  ```
</ParamField>

<ParamField path="openai" type="object" required={false}>
  OpenAI-specific options for GPT-5 and other OpenAI models.

  **Supported Options:**

  * `reasoningEffort`: Controls thinking effort for reasoning models (`'none'`, `'minimal'`, `'low'`, `'medium'`, `'high'`, `'xhigh'`)
  * `reasoningSummary`: Requests a streamed natural-language summary of the model's reasoning (`'auto'` or `'detailed'`), so the reasoning shows up inline in the [session trace](/reference/session-storage). **Defaults to `'auto'` on reasoning-capable models** (the reasoning tokens are billed either way, so the summary is near-free visibility). Non-reasoning models (e.g. `gpt-4o`) omit it.
  * `textVerbosity`: Controls response length and detail (`'low'`, `'medium'`, `'high'`)
  * `promptCacheKey`: Optional OpenAI prompt-cache routing key. AgentUse sets a stable default per agent when omitted.
  * `promptCacheRetention`: Optional OpenAI prompt-cache retention policy (`'in_memory'` or `'24h'`)
  * Defaults: when `reasoningEffort`, `textVerbosity`, or `promptCacheRetention` are omitted, AgentUse leaves them unset and uses the OpenAI/AI SDK defaults. When `promptCacheKey` is omitted, AgentUse generates a stable key per agent. `reasoningSummary` defaults to `'auto'` on reasoning-capable models; set it explicitly (or to disable, you currently cannot turn it off via config without leaving a non-reasoning model).

  ```yaml theme={"system"}
  openai:
    reasoningEffort: high       # More thorough reasoning
    reasoningSummary: auto      # Surface reasoning in the trace (default on reasoning models)
    textVerbosity: low          # Concise responses
    promptCacheRetention: 24h   # Optional extended prompt caching on supported models
  ```

  <Note>
    These options are particularly useful with GPT-5 models to balance response quality, latency, and cost. Some effort levels are model-specific; for example, `xhigh` and `none` are only accepted by OpenAI models that support them. Whether a reasoning summary actually streams depends on `reasoningEffort` and task complexity — the model may emit nothing for trivial tasks.
  </Note>
</ParamField>

<ParamField path="anthropic" type="object" required={false}>
  Anthropic-specific options for Claude models.

  **Supported Options:**

  * `thinking.budgetTokens`: Enables Claude [extended thinking](https://platform.claude.com/docs/en/build-with-claude/extended-thinking) with the given token budget (minimum `1024`). When set, Claude streams its reasoning, which appears inline in the [session trace](/reference/session-storage).

  ```yaml theme={"system"}
  anthropic:
    thinking:
      budgetTokens: 4096
  ```

  <Warning>
    Extended thinking is **off by default** and is an explicit opt-in: enabling it generates new thinking tokens billed at **output rates** (a real cost increase that scales with the budget). AgentUse automatically raises `max_tokens` above the budget to satisfy Anthropic's constraint and reserve room for the answer.
  </Warning>
</ParamField>

<ParamField path="skills" type="&#x22;auto&#x22; | &#x22;trusted&#x22; | string[] | object" required={false}>
  Controls which installed skills are available to the agent.

  Default: `auto`

  ```yaml theme={"system"}
  skills: auto
  ```

  `auto` preserves the default behavior: all discovered skills are available for on-demand loading when relevant.

  `trusted` keeps auto discovery and trusts loaded skills to use the tools already configured on the agent. It does not enable new tools or new bash commands:

  ```yaml theme={"system"}
  skills: trusted
  ```

  To preload a skill before the task starts, define it explicitly:

  ```yaml theme={"system"}
  skills: [linkedin]
  ```

  Add `allow` when a preloaded skill should grant a command family:

  ```yaml theme={"system"}
  skills:
    linkedin:
      allow: [agent-browser]
  ```

  Explicit skills are loaded into the agent's initial context. `allow` grants user-authored command families needed by that skill. For example, `agent-browser` expands to `agent-browser *`. AgentUse does not infer or validate command needs from skill text.

  You can combine auto discovery with explicit preloads:

  ```yaml theme={"system"}
  skills:
    auto: true
    linkedin:
      allow: [agent-browser]
  ```

  Use `allow: ["*"]` only for trusted skills that may use all tools already configured for the agent.

  <Tip>
    Run `agentuse doctor <agent-file>` to inspect skill grants.
    Doctor can show commands mentioned in the skill docs, but the output is advisory and not a permission manifest.
    Add `--last-run` to inspect the latest recorded session and diagnose actual blocked commands from runtime.
  </Tip>
</ParamField>

<ParamField path="sandbox" type="true | object" required={false}>
  Run agent commands inside an isolated Docker container. Requires Docker to be installed and running. Use `sandbox: true` for defaults or provide a config object.

  **Fields (when using object form):**

  * `provider`: Must be `docker` (required)
  * `image`: Docker image to use (default: `node:22-slim`)
  * `timeout`: Container timeout in seconds (default: `300`)
  * `setup`: Shell command(s) to run after container starts
  * `env`: Host env var names to forward into the container

  ```yaml theme={"system"}
  sandbox:
    provider: docker
    image: python:3.12-slim
    timeout: 600
    setup:
      - pip install pandas numpy
  ```

  When enabled, the agent receives `sandbox__exec` for running commands in the container. File I/O uses the existing filesystem tool — each filesystem path is mounted at its real host path with per-path ro/rw mode derived from permissions.

  <Note>
    This feature is experimental. See the [Sandbox guide](/guides/sandbox) for full documentation.
  </Note>
</ParamField>

<ParamField path="schedule" type="string" required={false}>
  Schedule for automatic agent execution in serve mode. The format is auto-detected.

  **Supported Formats:**

  * **Interval**: `5s`, `10m`, `2h` (sub-daily)
  * **Cron**: `"0 * * * *"`, `"0 9 * * 1-5"` (daily+)

  ```yaml theme={"system"}
  schedule: "30m"              # Every 30 minutes (interval)
  schedule: "0 9 * * 1-5"      # Weekdays at 9am (cron)
  ```

  <Note>
    Schedules only run when the agent is loaded via `agentuse serve`. Use `agentuse run` for one-off executions.
  </Note>
</ParamField>

<ParamField path="approval" type="boolean | object" required={false}>
  Add a human approval gate without putting approval instructions in the agent prompt.

  When `approval` is present, AgentUse automatically enables the internal `await_human` tool and injects the approval behavior for you. The markdown body should describe the work the agent needs to do; the YAML declares that the work must be reviewed before it is finalized.

  ```yaml theme={"system"}
  approval: true
  ```

  Optional timeout:

  ```yaml theme={"system"}
  approval:
    timeout: 24h
  ```

  **Fields:**

  * `timeout`: optional suspension timeout such as `24h` or `7d`. Approvals do not expire by default.

  Approval requests render best when the agent can provide `summary`, `draft` or `artifact_url`, `context`, and `risk` fields to the internal approval tool.

  You can define the approval boundary in the agent instructions. For example:

  ```md theme={"system"}
  You may create local drafts and preview artifacts without approval.
  Before scheduling, publishing, sending, deploying, merging, or changing external production state, request approval.
  Include the final content, target destination, timing, and risks in the approval request.
  ```

  See [Approval Gates](/guides/approval-gates) for the full setup guide and Approval API examples.
</ParamField>

<ParamField path="channels" type="array | object" required={false}>
  Configure optional external collaboration channels separately from approval policy.

  ```yaml theme={"system"}
  channels: [slack]
  ```

  ```yaml theme={"system"}
  channels:
    slack:
      events: [approval, completion, failure]
      channel_id: C0123456789
  ```

  **Fields:**

  * `channels`: `[slack]` enables Slack with default events and channel env fallback.
  * `channels.slack`: `true` or an object to enable Slack.
  * `channels.slack.enabled`: optional switch for temporarily disabling Slack.
  * `channels.slack.events`: event or list of events. Supported values are `approval`, `completion`, and `failure`. Use `completion`, not `complete` or `completed`.
  * `channels.slack.channel_id`: Slack channel id. If omitted, AgentUse uses `SLACK_APPROVAL_CHANNEL`.

  See [Channels](/guides/channels) for event semantics, Slack setup, and examples.
</ParamField>

## Tools Configuration

Tools are available to agents through:

1. **Built-in Tools** - Filesystem, Bash, and artifact tools with configurable permissions
2. **MCP Servers** - Connect to any Model Context Protocol server
3. **Sub-Agents** - Delegate tasks to other agents

### Built-in Tools

Configure filesystem, bash, and artifact tools via the `tools` field:

```yaml theme={"system"}
tools:
  filesystem:
    - path: ${root}
      permissions: [read, write]   # write also grants edit
  bash:
    commands:
      - "git *"
      - "npm *"
  artifacts: true                  # enables artifact_save and artifact_list
```

<Card title="Built-in Tools Reference" icon="wrench" href="/reference/builtin-tools">
  See full configuration options for filesystem, bash, and artifact tools
</Card>

## MCP Servers

### Stdio MCP Configuration

```yaml theme={"system"}
mcpServers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/directory", "--read-only"]
    requiredEnvVars:      # Variables that must exist
      - API_KEY
    allowedEnvVars:       # Optional variables
      - DEBUG_MODE
    disallowedTools:      # Optional: tools to exclude
      - write_file
      - delete_file
```

### HTTP MCP Configuration

```yaml theme={"system"}
mcpServers:
  remote_server:
    url: https://api.example.com/mcp
    sessionId: my-session-123           # Optional session ID
    auth:                               # Optional authentication
      type: bearer
      token: ${env:API_TOKEN}
    headers:                            # Optional custom headers
      X-Custom-Header: custom-value
    requiredEnvVars:                    # Variables that must exist
      - API_TOKEN
    allowedEnvVars:                     # Optional variables  
      - DEBUG_MODE
    disallowedTools:                    # Optional: tools to exclude
      - dangerous_operation
```

### Multiple MCP Servers

```yaml theme={"system"}
mcpServers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./data"]
  database:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-postgresql"]
    requiredEnvVars:
      - DATABASE_URL      # Must be set in .env or shell
  custom:
    command: node
    args: ["./custom-mcp-server.js"]
    allowedEnvVars:
      - CUSTOM_CONFIG     # Optional configuration
  http_api:
    url: https://api.example.com/mcp
    sessionId: unique-session-id
    auth:
      type: bearer
      token: ${env:API_TOKEN}
    requiredEnvVars:
      - API_TOKEN
```

<Note>
  The `mcpServers` field uses a map format where each server has a name as the key.
</Note>

## Sub-Agents

### Sub-Agent Configuration

```yaml theme={"system"}
subagents:
  - path: ./agents/researcher.agentuse
    name: researcher  # Optional custom name
    maxSteps: 100    # Optional step limit (default: 100)
  - path: ./agents/writer.agentuse
  - path: ../shared/validator.agentuse
```

### Remote Sub-Agents

```yaml theme={"system"}
subagents:
  - path: https://example.com/agents/helper.agentuse
  - path: https://raw.githubusercontent.com/user/repo/main/agent.agentuse
```

<Info>
  Sub-agents can call the main agent or other sub-agents, enabling complex multi-agent workflows.
</Info>

## Environment Variables in MCP Configuration

<Info>
  **Security by Design**: AgentUse prevents hardcoding secrets in agent files. Use `requiredEnvVars` and `allowedEnvVars` to control which environment variables are passed to MCP servers.
</Info>

```yaml theme={"system"}
mcpServers:
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    requiredEnvVars:
      - GITHUB_TOKEN      # Fails if not set
    allowedEnvVars:
      - GITHUB_DEBUG      # Optional, warns if missing
```

<Card title="Environment Variables - MCP Server Configuration" icon="shield-check" href="/reference/environment-variables#mcp-server-environment-variables">
  See the complete reference for security model, setting environment variables, error messages, and examples.
</Card>

### MCP Server Configuration Fields

#### Common Fields (All Server Types)

* **`requiredEnvVars`**: Variables that MUST exist. Agent fails if missing.
* **`allowedEnvVars`**: Optional variables to pass through if they exist.
* **`disallowedTools`**: Tool names/patterns to exclude (supports wildcards).

#### Stdio Server Fields

* **`command`**: Executable command (required). Relative paths resolve from agent file's directory.
* **`args`**: Command-line arguments (optional)
* **`env`**: Additional environment variables (optional)

#### HTTP Server Fields

* **`url`**: HTTPS URL of the MCP server (required)
* **`sessionId`**: Session identifier (optional)
* **`auth`**: Authentication config with `type: bearer` and `token` (supports `${env:VAR_NAME}`)
* **`headers`**: Custom HTTP headers (optional)

## System Prompt Sections

### Basic Structure

```markdown theme={"system"}
---
name: agent
model: anthropic:claude-sonnet-5
---

You are a helpful assistant.

## Your Role
Detailed description of the agent's role.

## Guidelines
- Guideline 1
- Guideline 2
- Guideline 3

## Task
What the agent should do.
```

### Using Context in Prompts

```markdown theme={"system"}
---
name: personalized
model: anthropic:claude-sonnet-5
---

You are a helpful AI assistant.

## Context
Provide assistance based on the user's specific needs and context.
```

<Note>
  Direct variable interpolation in prompts is not currently supported. Context should be provided through conversation or MCP tools.
</Note>

### Conditional Sections

```markdown theme={"system"}
---
name: adaptive
model: anthropic:claude-sonnet-5
---

You adapt based on user needs.

## For Technical Users
Provide detailed technical explanations.

## For Non-Technical Users
Use simple language and analogies.

## Task
Determine user level and respond appropriately.
```

## Special Syntax

### Commands

```markdown theme={"system"}
## Available Commands
!help - Show help
!reset - Reset context
!compact - Compact context
!status - Show status
```

### Structured Output

````markdown theme={"system"}
## Output Format
Return responses as JSON:
```json
{
  "status": "success",
  "data": "...",
  "metadata": {}
}
````

````

### Examples in Prompt

```markdown
## Examples

### Example 1
Input: "Translate hello to Spanish"
Output: "Hola"

### Example 2
Input: "What's 2+2?"
Output: "4"
````

## Complete Example

```markdown theme={"system"}
---
model: openai:gpt-5.5
description: "Multi-capability AI assistant with file, GitHub, and research capabilities"
timeout: 900
maxSteps: 150
openai:
  reasoningEffort: high
  textVerbosity: medium
mcpServers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "./data", "--read-only"]
  github:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    requiredEnvVars:
      - GITHUB_TOKEN      # Must be set in .env or shell
    allowedEnvVars:
      - GITHUB_DEBUG      # Optional debug flag
    disallowedTools:
      - delete_*          # Prevent deletion operations
  api_server:
    url: https://api.example.com/mcp
    sessionId: agent-session-123
    auth:
      type: bearer
      token: ${env:API_TOKEN}
    requiredEnvVars:
      - API_TOKEN
subagents:
  - path: ./helpers/researcher.agentuse
    name: researcher    # Optional custom name
    maxSteps: 100       # Optional step limit
  - path: ./helpers/writer.agentuse
---

# Multi-Capability Agent

You are an advanced AI assistant with multiple capabilities.

## Your Capabilities
1. **File Access**: Read and write files via the filesystem MCP server
2. **GitHub Access**: Interact with GitHub repositories
3. **Research**: Delegate research tasks to the researcher sub-agent
4. **Writing**: Delegate writing tasks to the writer sub-agent

## Guidelines
- Use the appropriate tool for each task
- Delegate complex tasks to specialized sub-agents
- Handle errors gracefully
- Provide clear, concise responses

## Task
Assist the user with their request using all available capabilities.
```

## Validation Rules

1. **File Extension**: Agent files must use `.agentuse` extension
2. **Model**: Must be a non-empty string (required field)
3. **MCP Server Configuration**:
   * Stdio servers: Must have `command` field
   * HTTP servers: Must have `url` field with `http://` or `https://` protocol
   * Cannot have both `command` and `url` in the same server config
4. **Environment Variables**:
   * `requiredEnvVars` and `allowedEnvVars` must be arrays of strings
   * Use `${env:VAR_NAME}` syntax to reference environment variables (e.g., in `auth.token`)
5. **Sub-agents**:
   * Must be an array of objects
   * Each object must have a `path` field (string)
   * Optional `name` (string) and `maxSteps` (number) fields
6. **Authentication**: Only `bearer` type is supported for HTTP MCP servers
7. **Tool Restrictions**: `disallowedTools` must be an array of strings (supports wildcards)
8. **OpenAI Options**:
   * `openai` field is only valid for OpenAI models
   * `reasoningEffort` must be one of: `'none'`, `'minimal'`, `'low'`, `'medium'`, `'high'`, `'xhigh'`
   * `textVerbosity` must be one of: `'low'`, `'medium'`, `'high'`
   * `promptCacheKey` must be a non-empty string of 64 characters or fewer
   * `promptCacheRetention` must be one of: `'in_memory'`, `'24h'`
   * No other options are allowed under `openai`

## Next Steps

<CardGroup cols={3}>
  <Card title="Sub-Agents" icon="users" href="/guides/subagents">
    Learn about sub-agents
  </Card>

  <Card title="Environment Variables" icon="gear" href="/reference/environment-variables">
    Configure environment
  </Card>

  <Card title="Examples" icon="code" href="https://github.com/agentuse/agentuse/tree/main/templates/agents">
    See it in action
  </Card>
</CardGroup>