> ## Documentation Index
> Fetch the complete documentation index at: https://docs.codemachine.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Basics

> Understand what an agent is, the different types, and when to use each one.

**An agent is a session of an AI coding engine.**

One agent equals one engine session with a unique ID. Each agent has its own engine, model, and configuration.

***

## What Makes Up an Agent

Every agent consists of:

* <Icon icon="message" /> **[Prompts](#prompts)** - The instructions sent to the agent
* <Icon icon="microchip" /> **[Engine](#engines)** - The AI coding CLI that powers the agent
* <Icon icon="brain" /> **[Model](#engines)** - The AI model the engine uses
* <Icon icon="hand" /> **[Interactivity](#interactivity)** - Whether the agent waits for input or runs automatically
* <Icon icon="plug" /> **[MCP](#mcp)** - External tools and integrations available to the agent

***

## Agent Types

<CardGroup cols={2}>
  <Card title="Main Agent" icon="robot" href="#main-agent">
    Runs as a step in the workflow. Does the primary work.
  </Card>

  <Card title="Module" icon="rotate" href="#module">
    A main agent that can loop back to earlier steps.
  </Card>

  <Card title="Sub-agent" icon="share-nodes" href="#sub-agent">
    Spawned by main agents via MCP to delegate work.
  </Card>

  <Card title="Controller" icon="gamepad" href="#controller">
    Orchestrates on your behalf - answers questions, signals next steps.
  </Card>
</CardGroup>

***

## When to Use Each Type

### Main Agent

Use for standard workflow steps that run once and pass output forward.

<Accordion title="Best for" icon="check" defaultOpen>
  * Single-pass tasks (analysis, generation, implementation)
  * Steps that don't need to revisit previous work
  * Most workflow steps
</Accordion>

<Card title="Configure Main Agents" icon="arrow-right" href="/build-workflows/build-agents#main-agents">
  Learn how to set up main agents
</Card>

### Module

Use when a step needs to loop back based on results.

<Accordion title="Best for" icon="check" defaultOpen>
  * Review and revision cycles
  * Iterative refinement
  * Quality gates that may require rework
</Accordion>

<Card title="Configure Modules" icon="arrow-right" href="/build-workflows/build-agents#modules">
  Learn how to set up modules
</Card>

### Sub-agent

Use to break complex work into delegated tasks within a single step.

<Accordion title="Best for" icon="check" defaultOpen>
  * Parallel task execution
  * Context isolation
  * Specialized subtasks
</Accordion>

<Note>
  Sub-agents are not steps. They are a context management tool for delegating work between agents.
</Note>

<Card title="Configure Sub-agents" icon="arrow-right" href="/build-workflows/build-agents#sub-agents">
  Learn how to set up sub-agents
</Card>

### Controller

Use for autonomous workflows where you want an agent to make decisions between steps.

<Accordion title="Best for" icon="check" defaultOpen>
  * Long-running autonomous workflows
  * Tasks where you want to review results, not manage process
  * Complex multi-step operations with clear objectives
</Accordion>

<Card title="Configure Controllers" icon="arrow-right" href="/build-workflows/build-agents#controllers">
  Learn how to set up controllers
</Card>

***

## Agent vs Step

| Concept   | What It Is                                    |
| --------- | --------------------------------------------- |
| **Step**  | A position in the workflow sequence           |
| **Agent** | The AI session that executes at that position |

Every step has exactly one agent. The step defines when to run. The agent defines how to run.

***

## Engines

An engine is an AI coding CLI that powers the agent. Different engines have different capabilities, strengths, and supported models.

Why this matters: You can mix engines in a single workflow—use one engine for creative tasks, another for complex reasoning, and a fast one for simple operations.

<Card title="Configure Engines & Models" icon="arrow-right" href="/build-workflows/model-configuration">
  See available engines, model options, and configuration examples
</Card>

***

## Interactivity

Interactivity determines whether an agent waits for input or proceeds automatically.

<Tabs>
  <Tab title="Interactive" icon="hand">
    **Agent waits for user input.**

    * Pauses after each prompt
    * User reviews and responds
    * Best for exploration and Q\&A
  </Tab>

  <Tab title="Non-Interactive" icon="bolt">
    **Agent proceeds automatically.**

    * No pauses between prompts
    * Runs to completion
    * Best for automated pipelines
  </Tab>
</Tabs>

<Info>
  This is how hybrid workflows work - some agents wait for you, others run automatically.
</Info>

<Card title="Configure Interactivity" icon="arrow-right" href="/build-workflows/your-first-workflow#interactive-vs-non-interactive-steps">
  Learn how to set interactive or non-interactive mode per agent
</Card>

***

## MCP

MCP (Model Context Protocol) servers extend agent capabilities with additional tools.

**What MCP provides:**

* <Icon icon="plug" /> Custom tool integrations
* <Icon icon="database" /> External data access
* <Icon icon="share-nodes" /> Sub-agent spawning
* <Icon icon="bell" /> Signals for workflow control

<Note>
  The signals MCP is required for autonomous workflows where agents need to communicate with the controller. It's also required when using sub-agents, since agent coordination works through MCP.
</Note>

<Card title="Configure MCP" icon="arrow-right" href="/build-workflows/build-agents#built-in-mcp-servers">
  Learn how to add MCP servers to your agents
</Card>

***

## Prompts

Prompts are the instructions sent to an agent. They define what the agent should do.

### Chained Prompts

Multiple prompts injected into the same agent session, one after another. Instead of overwhelming one step with all instructions, you break it into smaller sequential prompts.

**Example flow:**

1. First prompt: "Analyze the codebase structure"
2. User reviews output
3. Second prompt: "Based on your analysis, identify potential issues"
4. User reviews output
5. Third prompt: "Create a plan to address the top 3 issues"

<Info>
  Same agent, same session. Prompts run in sequence. Common in interactive Q\&A workflows.
</Info>

<Card title="Configure Chained Prompts" icon="arrow-right" href="/build-workflows/write-prompts">
  Learn how to set up sequential prompts for an agent
</Card>

### Placeholders

Placeholders inject data into agent prompts.

| Type                | Source                                    | Use case                                    |
| ------------------- | ----------------------------------------- | ------------------------------------------- |
| Static (packageDir) | Pre-defined prompts from workflow package | Shared prompts, split large prompts         |
| Dynamic (userDir)   | Files created during workflow             | Agent A outputs a file, Agent B receives it |

<Icon icon="gear" /> **Built-in Placeholders:** System data injected automatically - date, time, username, project name, selected tracks and conditions.

<Card title="Configure Placeholders" icon="arrow-right" href="/build-workflows/write-prompts#placeholders">
  Learn how to use static and dynamic placeholders in prompts
</Card>

### Directives

Directives allow agents to control the workflow by writing to a JSON file. The workflow listens after each step and takes action.

| Directive    | Action                                            |
| ------------ | ------------------------------------------------- |
| `checkpoint` | Shows message to user, option to continue or stop |
| `stop`       | Stops the workflow                                |
| `error`      | Shows error message and stops                     |
| `pause`      | Pauses and waits for user input                   |
| `loop`       | Returns back to a previous step (modules only)    |
| `trigger`    | Triggers any agent in the workflow (modules only) |

<Note>
  Directives come from agents. Signals come from users. Both control execution, but from different sources.
</Note>

<Card title="Configure Directives" icon="arrow-right" href="/build-workflows/write-prompts#module-prompts">
  Learn how to enable agents to control workflow execution
</Card>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Your First Workflow" icon="rocket" href="/build-workflows/your-first-workflow">
    Build a complete workflow from scratch
  </Card>

  <Card title="Build Agents" icon="robot" href="/build-workflows/build-agents">
    Configure agents for your workflow
  </Card>
</CardGroup>