Skip to main content

​
Agent File Format

AgentUse agents are markdown files with a .agentuse extension. They consist of:
  1. Frontmatter - YAML configuration
  2. Agent Prompt - Agent instructions

​
Basic Structure

---
model: anthropic:claude-sonnet-4-0
description: "General-purpose AI assistant for various tasks"
---

You are a helpful assistant.

## Task
Help the user with their request.
The agent name is automatically derived from the filename. You don’t need to specify it in the frontmatter.

​
Frontmatter Configuration

​
Required Field

​
model
string
required
The AI model to use. Format: provider:model-nameExamples:
  • anthropic:claude-opus-4-1
  • anthropic:claude-sonnet-4-0
  • anthropic:claude-3-5-haiku-latest
  • openai:gpt-5
  • openai:gpt-5-mini
  • openai:gpt-5-nano
  • openrouter:meta/llama-3-70b
You can also specify environment variable suffixes:
  • anthropic:claude-sonnet-4-0:dev (uses ANTHROPIC_API_KEY_DEV)
  • openai:gpt-5:prod (uses OPENAI_API_KEY_PROD)
  • openai:gpt-5:OPENAI_API_KEY_PERSONAL (uses specific env var)

​
Optional Fields

​
description
string
A concise description of the agent’s purpose.This appears in:
  • Tool descriptions when used as a sub-agent
  • CLI output when running the agent
  • Plugin events for logging
Best practices:
  • Keep under 80-120 characters
  • Be action-oriented
  • Focus on primary capability
​
mcp_servers
object
MCP server configurations. Each server can have:
  • command + args: For stdio-based servers
  • url: For HTTP-based servers
  • env: Environment variables for the server
  • requiredEnvVars: Required environment variables (fail if missing)
  • allowedEnvVars: Optional environment variables to pass
  • disallowedTools: Array of tool names/patterns to exclude
  • auth: Authentication for HTTP servers
  • headers: HTTP headers for HTTP servers
​
subagents
array
List of sub-agent configurations. Each sub-agent can have:
  • path: Path to the agent file (required)
  • name: Optional custom name for the sub-agent
  • maxSteps: Optional maximum number of steps the sub-agent can take

​
MCP Server Integration

Connect to Model Context Protocol servers: 
---
model: anthropic:claude-sonnet-4-0
description: "File system and GitHub integration agent"
mcp_servers:
  filesystem:
    command: "pnpx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/documents"]
    disallowedTools: ["*delete*"]  # Exclude dangerous operations
  github:
    command: "pnpx"
    args: ["-y", "@modelcontextprotocol/server-github"]
    requiredEnvVars: ["GITHUB_TOKEN"]  # Will fail if missing
    env:
      GITHUB_TOKEN: ${GITHUB_TOKEN}
---
MCP servers provide standardized access to external tools and data sources. Each server needs a unique name (key) in the mcp_servers object.

​
HTTP MCP Servers

---
model: anthropic:claude-sonnet-4-0
mcp_servers:
  remote_api:
    url: https://api.example.com/mcp
    sessionId: "unique-session-id"
    auth:
      type: bearer
      token: ${API_TOKEN}
    headers:
      X-Custom-Header: "custom-value"
    allowedEnvVars: ["API_TOKEN", "API_REGION"]
---

​
Using Sub-Agents

Agents can delegate to other agents. All sub-agent paths are resolved relative to the parent agent file’s directory: 
---
model: anthropic:claude-sonnet-4-0
description: "Coordinator agent that manages research and writing tasks"
subagents:
  - path: ./research-agent.agentuse      # Same directory as parent
    name: "research_specialist"          # Optional custom name
    maxSteps: 100                         # Optional: limit sub-agent steps
  - path: ../utils/writer-agent.agentuse # Parent directory
  - path: ./team/editor.agentuse         # Subdirectory
---

You coordinate between research and writing agents.

## Task
When asked to create content:
1. Use the research agent to gather information
2. Use the writer agent to create the content
Sub-agents can be local files or HTTPS URLs. Remote agents must end with .agentuse extension.

​
Environment Variables

Environment variables are used in MCP server configurations, not directly in the agent frontmatter.

​
Using Environment Variables in MCP

---
model: anthropic:claude-sonnet-4-0
mcp_servers:
  api_server:
    command: ./api-server
    requiredEnvVars: ["API_KEY"]
    allowedEnvVars: ["API_URL", "DEBUG"]
    env:
      API_URL: ${API_URL:-https://api.example.com}  # With default
---

​
System Environment Variables

The following environment variables affect agent behavior:
  • MAX_STEPS - Maximum conversation turns (default: 1000)
  • ANTHROPIC_API_KEY - For Anthropic models
  • OPENAI_API_KEY - For OpenAI models
  • OPENROUTER_API_KEY - For OpenRouter models
  • CONTEXT_COMPACTION - Enable/disable context compaction (default: enabled, set to ‘false’ to disable)
  • COMPACTION_THRESHOLD - Token threshold for compaction (default: varies by model)
  • COMPACTION_KEEP_RECENT - Number of recent messages to keep during compaction (default: varies)

​
Runtime Customization

You can append additional prompts when running agents without modifying the agent file: 
# Run with base instructions
agentuse run code-review.agentuse

# Add specific focus areas
agentuse run code-review.agentuse "focus on security and performance"

# Customize behavior temporarily
agentuse run assistant.agentuse "respond in a formal tone"

# Provide additional context
agentuse run analyzer.agentuse "use production database settings"
This is useful for:
  • Testing different approaches without editing files
  • Providing context-specific instructions
  • Reusing agents with slight variations
  • Quick experimentation

​
Examples

For a comprehensive collection of agent examples, including data analysis, code review, API integration, and more, visit the AgentUse Templates.

​
Project Structure and Path Resolution

​
Project Root Detection

AgentUse automatically detects your project root by searching upward for .git/, .agentuse/, or package.json. 
my-agent-project/
├── .env                    # Project-wide environment variables
├── .agentuse/
│   └── plugins/           # Custom plugins
│       └── logger.js
├── agents/
│   ├── main.agentuse      # Main orchestrator
│   ├── research/
│   │   ├── web.agentuse
│   │   └── docs.agentuse
│   └── processing/
│       ├── analyzer.agentuse
│       └── formatter.agentuse
├── utils/
│   ├── helper.agentuse
│   └── validator.agentuse
└── tools/
    └── custom-mcp-server  # Custom MCP server executable

​
Path Resolution Examples

# In agents/main.agentuse
---
model: anthropic:claude-sonnet-4-0
subagents:
  # Paths relative to agents/main.agentuse location
  - path: ./research/web.agentuse      # → agents/research/web.agentuse
  - path: ../utils/helper.agentuse     # → utils/helper.agentuse
mcp_servers:
  custom:
    # Command paths relative to agents/main.agentuse location
    command: ../tools/custom-mcp-server  # → tools/custom-mcp-server
---
You can run this from anywhere: 
# From project root
agentuse run agents/main.agentuse

# From any subdirectory
cd agents/research
agentuse run ../main.agentuse

# From outside the project
agentuse run /path/to/project/agents/main.agentuse

# Override project root if needed
agentuse run agent.agentuse -C /different/project

​
Benefits of This Structure

  1. Portability: Share entire agent projects without breaking paths
  2. Organization: Clear separation of concerns
  3. Reusability: Utils and helpers can be shared across agents
  4. Version Control: Everything in one repository
  5. Environment Management: Single .env file for all agents

​
Next Steps

Sub-Agents

Learn about delegating tasks to other agents

Agent Design Patterns

Best practices and patterns for building agents

Examples

See more agent examples
⌘I