Agent Syntax Reference

---
# YAML configuration
name: agent-name
model: provider:model
---

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

## Optional sections
Additional instructions or context.

tools:
  filesystem:
    - path: ${root}
      permissions: [read, write]   # write also grants edit
  bash:
    commands:                      # auto-run allowlist
      - "git *"
      - "npm *"
    gated:                         # run only after human approval (per-action lease)
      - "npm publish *"
  artifacts: true                  # enables artifact_save and artifact_list
  metrics: true                    # enables record_metric

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
    toolTimeout: 90       # Optional per-tool-call timeout: bare number = seconds
                          # (default 60), or a duration string like "2m".
                          # Env fallback: MCP_TOOL_TIMEOUT (seconds).

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

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

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

subagents:
  - path: https://example.com/agents/helper.agentuse
  - path: https://raw.githubusercontent.com/user/repo/main/agent.agentuse

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

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

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

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

## Available Commands
!help - Show help
!reset - Reset context
!compact - Compact context
!status - Show status

## 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"

---
model: openai:gpt-5.6
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.