## Overview

The Agents page lets you create and manage **model stacks** - custom configurations that define how AI agents work together to handle your requests. Build multi-agent teams where a coordinator routes work to specialized experts, optimizing both quality and cost.

## What Are Model Stacks?

A **model stack** is a user-defined configuration that combines:

- **A coordinator agent** (required) - handles all requests and routes to specialists
- **Specialist agents** (optional) - experts for specific tasks (research, coding, architecture, UI/UX)
- **Context optimization** - reduces tokens and costs while improving quality
- **Per-agent model assignments** - choose which LLM each agent uses

Think of it as building your own AI team where each member specializes in different areas and uses the model best suited for their role.

## Key Features

<CardGroup cols={2}>
  <Card title="Multi-Agent Teams" icon="groups">
    Combine coordinator with specialists for different workflows and use cases.
  </Card>
  <Card title="Cost Control" icon="savings">
    Assign cheaper models to specialists, expensive models only where needed.
  </Card>
  <Card title="Quality Optimization" icon="verified">
    Use appropriate models for each task - Opus for architecture, Sonnet for
    research.
  </Card>
  <Card title="Performance Analytics" icon="analytics">
    Track latency, cost, and error rates per agent in each stack.
  </Card>
</CardGroup>

## Available Agents

ModelStack provides six pre-configured agent roles:

| Agent                | Role                  | Default Model     | Best For                               |
| -------------------- | --------------------- | ----------------- | -------------------------------------- |
| **Coordinator**      | Main handler & router | Claude Sonnet 4.6 | Routing, synthesis, user interaction   |
| **Senior Architect** | Architecture expert   | Claude Opus 4.6   | System design, architectural decisions |
| **Researcher**       | Technical research    | Claude Sonnet 4.6 | Documentation, API exploration         |
| **Coder**            | Code generation       | Claude Opus 4.6   | Writing production code                |
| **Reviewer**         | Code review           | Claude Opus 4.6   | Quality checks, bug detection          |
| **Senior UI/UX**     | UI/UX design          | Claude Opus 4.6   | Interface design, user experience      |
| **Senior Frontend**  | Frontend architecture | Claude Opus 4.6   | Frontend patterns, component design    |

<Note>
  Each agent has specialized system prompts and capabilities tailored to their
  role. The coordinator is required; specialists are optional.
</Note>

## Creating a Model Stack

### Step 1: Open Stack Creator

1. Navigate to **Dashboard → Agents**
2. Click **New Agent** button
3. Stack configuration modal opens

### Step 2: Configure Basic Settings

**Stack ID** (required):

- Unique identifier for this stack
- Format: lowercase letters, numbers, hyphens, dots
- Example: `code-review-strict`, `prototype-fast`, `docs-writer`
- Maximum 64 characters
- Used when making API calls: `"model": "your-stack-id"`

**Display Name** (optional):

- Human-readable name for the dashboard
- Example: "Code Review (Strict)", "Fast Prototyping"

### Step 3: Assign Coordinator

**Coordinator Agent** (required):

- Choose the model for your main coordinator
- This agent handles all user requests
- Decides when to consult specialists
- Synthesizes responses from multiple agents

**Model Selection:**

- Use **Claude Sonnet 4.6** for balanced performance (recommended)
- Use **Claude Opus 4.6** for maximum quality
- Use **GPT-4o** for vision capabilities
- Use **GPT-4o-mini** for cost optimization

### Step 4: Add Specialists (Optional)

Add specialist agents based on your workflow needs:

**For Code-Heavy Workflows:**

- Add **Coder** - generates production code
- Add **Reviewer** - checks code quality
- Coordinator routes coding tasks to these specialists

**For Architecture Work:**

- Add **Senior Architect** - designs system architecture
- Add **Researcher** - explores technical options
- Coordinator consults them for big decisions

**For UI/UX Projects:**

- Add **Senior UI/UX** - designs interfaces
- Add **Senior Frontend** - implements frontend patterns
- Coordinator routes design/frontend tasks to them

<Info>
  You can add any combination of specialists. The coordinator will intelligently
  route requests based on the task type.
</Info>

**Response mode** (per specialist):

Every specialist has a response mode, set on the node or in its side panel.

- **Advise** (default): the specialist's answer goes back to the coordinator as
  advice. The coordinator combines it with everything else it knows and writes
  the final response.
- **Delegate**: when the specialist gives a final answer, it is sent to the user
  exactly as written. The coordinator hands off and adds nothing. If the
  specialist needs more context, that request still goes through the
  coordinator first.

Only specialists can delegate; the coordinator always uses Advise.

### Step 5: Configure Context Optimization

Choose how to reduce token usage while maintaining quality:

| Mode              | How It Works                    | Best For                            |
| ----------------- | ------------------------------- | ----------------------------------- |
| **None**          | Full context sent to LLM        | Small contexts, maximum accuracy    |
| **Compact**       | LLM rewrites query smaller      | Medium contexts, balanced approach  |
| **Retrieve**      | AST-based semantic search       | Large codebases, targeted retrieval |
| **History Guard** | Chunks old conversation         | Long conversations, stateless       |
| **History Brain** | Cross-request memory with dedup | Multi-session projects, stateful    |
| **Auto**          | Automatically selects best mode | Most use cases (recommended)        |

**Recommendations:**

- **Auto** - Let the system choose (works for most scenarios)
- **Retrieve** - Large codebases with hundreds of files
- **History Brain** - Long-running projects with multiple sessions
- **None** - Short, one-off requests where token count isn't a concern

### Step 6: Create Stack

Click **Create Stack** to save your configuration.

Your new stack is now available and can be used via API:

```bash
curl https://api.modelstack.cc/v1/chat/completions \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "your-stack-id",
    "messages": [
      {"role": "user", "content": "Design a user authentication system"}
    ]
  }'
```

## Managing Stacks

### Viewing Your Stacks

The Agents page displays all your stacks in a list:

- **Stack name** - Display name or Stack ID
- **Agents count** - Number of agents in the stack
- **Context mode** - Current optimization setting
- **Actions** - View analytics, edit, or delete

### Editing a Stack

1. Click on a stack card
2. Update display name, agents, or context mode
3. Click **Save Changes**

<Warning>
  Changing the Stack ID is not allowed after creation. If you need a different
  ID, create a new stack and delete the old one.
</Warning>

### Deleting a Stack

1. Click **Delete** on a stack card
2. Confirm deletion
3. Stack is permanently removed

<Warning>
  Deletion is permanent and cannot be undone. API calls using this stack ID will
  fail after deletion.
</Warning>

### Viewing Stack Analytics

Click **View Analytics** to see detailed performance metrics:

- **Total requests** - How many times this stack was called
- **Average latency** - Response time in milliseconds
- **Total cost** - Spending in millidollars
- **Error rate** - Percentage of failed requests
- **Per-agent breakdown** - Which agents were consulted and their performance
- **Call graph** - Visual map of agent interactions
- **Cost breakdown** - Spending by agent over time

## Use Cases & Examples

### Use Case 1: Code Review Workflow

**Goal:** Strict code review with architectural oversight

**Configuration:**

```
Stack ID: code-review-strict
Coordinator: Claude Sonnet 4.6
Specialists:
  - Reviewer (Claude Opus 4.6) - High-quality code review
  - Senior Architect (Claude Opus 4.6) - Architecture validation
Context Mode: Auto
```

**How it works:**

1. User submits code for review
2. Coordinator analyzes the submission
3. Coordinator consults Reviewer for code quality
4. Coordinator consults Senior Architect for design patterns
5. Coordinator synthesizes feedback and returns comprehensive review

**Cost optimization:**

- Coordinator uses Sonnet (cheaper, handles routing)
- Specialists use Opus only when consulted (expensive but accurate)

### Use Case 2: Fast Prototyping

**Goal:** Quick code generation for prototypes

**Configuration:**

```
Stack ID: prototype-fast
Coordinator: GPT-4o-mini
Specialists:
  - Coder (Claude Sonnet 4.6) - Balanced speed/quality
Context Mode: Compact
```

**How it works:**

1. User requests feature implementation
2. Coordinator (fast, cheap) routes to Coder
3. Coder generates code quickly
4. Coordinator returns response

**Cost optimization:**

- GPT-4o-mini coordinator = 0.15/1M tokens input
- Only consults Coder when needed
- Compact mode reduces context tokens

### Use Case 3: Documentation Writer

**Goal:** Research and write technical documentation

**Configuration:**

```
Stack ID: docs-writer
Coordinator: Claude Sonnet 4.6
Specialists:
  - Researcher (Claude Sonnet 4.6) - Explores APIs and docs
Context Mode: Retrieve
```

**How it works:**

1. User asks to document a system
2. Coordinator consults Researcher to explore codebase
3. Researcher uses AST retrieval to find relevant code
4. Coordinator synthesizes documentation

**Cost optimization:**

- Both use Sonnet (balanced cost/quality)
- Retrieve mode searches codebase efficiently
- Avoids sending entire codebase to LLM

### Use Case 4: UI/UX Design Sprint

**Goal:** Design and implement UI components

**Configuration:**

```
Stack ID: ui-design-sprint
Coordinator: Claude Opus 4.6
Specialists:
  - Senior UI/UX (Claude Opus 4.6) - Interface design
  - Senior Frontend (Claude Opus 4.6) - Component architecture
  - Coder (Claude Sonnet 4.6) - Implementation
Context Mode: History Brain
```

**How it works:**

1. User requests UI component design
2. Coordinator consults Senior UI/UX for design
3. Coordinator consults Senior Frontend for architecture
4. Coordinator consults Coder for implementation
5. History Brain remembers design decisions across sessions

**Why premium models:**

- UI/UX requires high-quality design thinking
- Frontend architecture needs deep React/component knowledge
- Only Coder uses Sonnet (implementation is more straightforward)

## Best Practices

### Cost Optimization

1. **Use Sonnet for coordinators** - They handle simple routing tasks
2. **Use Opus for specialists** - Only consulted when needed
3. **Enable context optimization** - "Auto" mode works well for most cases
4. **Monitor analytics** - Check which agents are called most, optimize their models

### Quality Optimization

1. **Match agent to task** - Use Coder for code, Reviewer for review, etc.
2. **Don't skip specialists** - They significantly improve quality
3. **Use Opus for critical work** - Architecture, security reviews, production code
4. **Use "History Brain" for projects** - Remembers context across sessions

### Workflow Design

1. **Start simple** - Coordinator only, add specialists as needed
2. **Test iteratively** - Create test stack, try different configurations
3. **Measure performance** - Use analytics to validate improvements
4. **Name stacks clearly** - Descriptive Stack IDs help team collaboration

## Common Questions

<AccordionGroup>
  <Accordion title="Can I have multiple coordinators?">
    No, each stack has exactly one coordinator. The coordinator is the main
    handler that routes to specialists. If you need different coordination
    strategies, create multiple stacks.
  </Accordion>
  <Accordion title="What happens if I don't add specialists?">
    The coordinator handles everything alone. This works fine for simple use
    cases but may miss specialized expertise. For example, coordinator-only
    won't get code review quality of a dedicated Reviewer agent.
  </Accordion>
  <Accordion title="How does context optimization reduce costs?">
    Context optimization modes reduce the number of tokens sent to LLMs: -
    **Compact** - Rewrites query to be shorter - **Retrieve** - Sends only
    relevant code chunks - **History Guard/Brain** - Summarizes old conversation
    turns Fewer input tokens = lower cost per request.
  </Accordion>
  <Accordion title="Can I use non-Claude models?">
    Yes! You can assign any model from the catalog to any agent. For example,
    use GPT-4o for vision tasks, GPT-5 for reasoning, or Gemini 2.5 Pro for long
    context.
  </Accordion>
  <Accordion title="What's the difference between History Guard and History Brain?">
    **History Guard** is stateless - compacts context per request but doesn't
    remember across requests. **History Brain** is stateful - stores session
    memory in database, remembers decisions across multiple API calls. Use Brain
    for long-running projects.
  </Accordion>
  <Accordion title="Do I need to change my code to use stacks?">
    Minimal changes. Just change the `model` parameter: ```diff - "model":
    "claude-sonnet-4-6" + "model": "your-stack-id" ``` Everything else stays the
    same.
  </Accordion>
</AccordionGroup>

## Related Documentation

- [API Reference](/docs/api-reference/chat-completions) - Using stacks in API requests
- [Billing & Balance](/docs/billing/balance) - How stack usage affects spending caps
- [Models](/docs/dashboard/models) - Browse available models for agents
- [Settings](/docs/dashboard/settings) - Configure model routing and preferences