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-5
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-5
  • anthropic:claude-sonnet-4-5
  • anthropic:claude-haiku-4-5
  • openai:gpt-5
  • openai:gpt-5-mini
  • openai:gpt-5-nano
  • openrouter:z-ai/glm-4.7
You can also specify environment variable suffixes:
  • anthropic:claude-sonnet-4-5: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
​
mcpServers
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 for external tools and data sources: 
---
model: anthropic:claude-sonnet-4-5
mcpServers:
  filesystem:
    command: "pnpx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
---

Agent Syntax - MCP Servers

See the complete reference for stdio servers, HTTP servers, environment variables, authentication, and tool restrictions.

​
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-5
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 configure API keys, behavior settings, and MCP server credentials.

Environment Variables Reference

See the complete reference for API keys, behavior control, MCP server configuration, and security best practices.

​
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

All paths (subagents, MCP server commands) are resolved relative to the agent file’s directory, ensuring portability.
See Agent Syntax - Subagents for complete path resolution examples.

​
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