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

# Creating Agents

> Define AI agents in markdown and run on cron, CI/CD, or serverless

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

```markdown theme={"system"}
---
model: anthropic:claude-sonnet-5
description: "General-purpose AI assistant for various tasks"
---

You are a helpful assistant.

## Task
Help the user with their request.
```

<Note>
  The agent name is automatically derived from the filename. You don't need to specify it in the frontmatter.
</Note>

## Frontmatter Configuration

### Required Field

<ParamField path="model" type="string" required>
  The AI model to use. Format: `provider:model-name`

  Examples:

  * `anthropic:claude-opus-4-8`
  * `anthropic:claude-sonnet-5`
  * `anthropic:claude-haiku-4-5`
  * `openai:gpt-5.5`
  * `openai:gpt-5.4-mini`
  * `openai:gpt-5.4-nano`
  * `openrouter:z-ai/glm-5.2`

  You can also specify environment variable suffixes:

  * `anthropic:claude-sonnet-5:dev` (uses ANTHROPIC\_API\_KEY\_DEV)
  * `openai:gpt-5.5:prod` (uses OPENAI\_API\_KEY\_PROD)
  * `openai:gpt-5.5:OPENAI_API_KEY_PERSONAL` (uses specific env var)
</ParamField>

### Optional Fields

<ParamField path="description" type="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
</ParamField>

<ParamField path="mcpServers" type="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
</ParamField>

<ParamField path="subagents" type="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
</ParamField>

## MCP Server Integration

Connect to Model Context Protocol servers for external tools and data sources:

```yaml theme={"system"}
---
model: anthropic:claude-sonnet-5
mcpServers:
  filesystem:
    command: "pnpx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "."]
---
```

<Card title="Agent Syntax - MCP Servers" icon="plug" href="/reference/agent-syntax#mcp-servers">
  See the complete reference for stdio servers, HTTP servers, environment variables, authentication, and tool restrictions.
</Card>

## Using Sub-Agents

Agents can delegate to other agents. All sub-agent paths are resolved relative to the parent agent file's directory:

```yaml theme={"system"}
---
model: anthropic:claude-sonnet-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
```

<Info>
  Sub-agents can be local files or HTTPS URLs. Remote agents must end with `.agentuse` extension.
</Info>

## Environment Variables

Environment variables configure API keys, behavior settings, and MCP server credentials.

<Card title="Environment Variables Reference" icon="gear" href="/reference/environment-variables">
  See the complete reference for API keys, behavior control, MCP server configuration, and security best practices.
</Card>

## Runtime Customization

You can append additional prompts when running agents without modifying the agent file:

```bash theme={"system"}
# 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](https://github.com/agentuse/agentuse/tree/main/templates/agents).

## Project Structure and Path Resolution

### Project Root Detection

AgentUse automatically detects your project root by searching upward for `.git/`, `.agentuse/`, or `package.json`.

### Recommended Project Structure

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

<Info>
  See [Agent Syntax - Subagents](/reference/agent-syntax#subagents) for complete path resolution examples.
</Info>

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

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

  <Card title="Agent Design Patterns" icon="diagram-project" href="/guides/agent-design-patterns">
    Best practices and patterns for building agents
  </Card>

  <Card title="Examples" icon="code" href="https://github.com/agentuse/agentuse/tree/main/templates/agents">
    See more agent examples
  </Card>
</CardGroup>