> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/rowboatlabs/rowboat/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent System Overview

> Introduction to the Rowboat agent system architecture and core concepts

The Rowboat agent system provides a flexible, multi-agent architecture for building autonomous workflows powered by large language models.

## Core Concepts

### What are Agents?

Agents are autonomous units that execute tasks using LLMs, tools, and instructions. Each agent:

* Runs with a specific **language model** (GPT-4, Claude, Gemini, etc.)
* Has access to **tools** (builtin commands, MCP integrations, or other agents)
* Follows **instructions** defined in Markdown
* Maintains **message history** and conversation state
* Can **call other agents** as tools for complex workflows

### Agent Types

> **Interactive Agents**
>
> Interactive agents work directly with users in real-time conversations. The main interactive agent is the **Copilot**, which:
>
> * Responds to user messages in the UI
> * Has access to workspace operations (file management, code execution)
> * Can load specialized skills on-demand
> * Executes MCP tools directly on behalf of users
>
> Location: `apps/x/packages/core/src/application/assistant/agent.ts:14`

> **Background Agents**
>
> Background agents run autonomously on schedules without user interaction. They:
>
> * Execute on **cron schedules**, **time windows**, or **once** at specific times
> * Run unattended workflows (email digests, data sync, monitoring)
> * Are configured in `~/.rowboat/config/agent-schedule.json`
> * Stored as Markdown files in `agents/` directory
>
> See [Background Agents](/platform/agents/background-agents) for details.

> **Multi-Agent Workflows**
>
> Agents can orchestrate other agents by declaring them as tools:
>
> ```yaml theme={null}
> tools:
>   summarizer:
>     type: agent
>     name: summarizer_agent
> ```
>
> This enables:
>
> * Task delegation to specialized agents
> * Complex multi-step workflows
> * Reusable agent components
> * Data flow through tool calls and responses

## Agent Definition Format

Agents are defined as **Markdown files with YAML frontmatter**:

```markdown theme={null}
---
model: gpt-5.1
provider: openai
tools:
  bash:
    type: builtin
    name: executeCommand
  search:
    type: mcp
    name: firecrawl_search
    description: Search the web
    mcpServerName: firecrawl
    inputSchema:
      type: object
      properties:
        query:
          type: string
      required:
        - query
---
# Research Agent

You are a research agent. Use the search tool to find information,
then execute bash commands to save results.

Be thorough and cite your sources.
```

### Frontmatter Fields

| Field | Required | Description |
| - | - | - |
| `model` | No | Model ID (e.g., `gpt-5.1`, `claude-sonnet-4-5`) |
| `provider` | No | Provider alias from `models.json` |
| `tools` | No | Object mapping tool keys to tool definitions |

### Instructions (Body)

The Markdown content after the frontmatter contains the agent's system instructions. Use standard Markdown formatting to structure guidance, examples, and behavioral rules.

## Tool Types

> **Builtin Tools**
>
> Internal Rowboat capabilities:
>
> ```yaml theme={null}
> bash:
>   type: builtin
>   name: executeCommand
> ```
>
> Common builtin tools:
>
> * `executeCommand` - Run shell commands
> * `workspace-readFile`, `workspace-writeFile` - File operations
> * `workspace-readdir`, `workspace-mkdir` - Directory operations
> * `analyzeAgent` - Inspect agent structure
> * `listMcpServers`, `listMcpTools`, `executeMcpTool` - MCP integration
> * `loadSkill` - Load skill definitions
>
> Location: `apps/x/packages/core/src/application/lib/builtin-tools.ts:183`

> **MCP Tools**
>
> External capabilities from Model Context Protocol servers:
>
> ```yaml theme={null}
> search:
>   type: mcp
>   name: firecrawl_search
>   description: Search the web
>   mcpServerName: firecrawl
>   inputSchema:
>     type: object
>     properties:
>       query:
>         type: string
>         description: Search query
>     required:
>       - query
> ```
>
> Required fields:
>
> * `type`: Must be "mcp"
> * `name`: Exact tool name from MCP server
> * `description`: What the tool does
> * `mcpServerName`: Server name from `config/mcp.json`
> * `inputSchema`: Full JSON Schema for parameters
>
> Use `listMcpTools` to discover available tools and their schemas.

> **Agent Tools**
>
> Reference other agents to build workflows:
>
> ```yaml theme={null}
> summarizer:
>   type: agent
>   name: summarizer_agent
> ```
>
> The target agent file must exist (e.g., `agents/summarizer_agent.md`). When called, the agent receives the input message and returns its final response as tool output.

## Agent State Management

The agent runtime maintains state throughout execution:

> [!NOTE]
>
> **AgentState** tracks messages, tool calls, permissions, and subflow states.
>
> Location: `apps/x/packages/core/src/agents/runtime.ts:484`

### State Properties

* `messages` - Full conversation history
* `agent` - Loaded agent definition
* `toolCallIdMap` - Maps tool call IDs to tool call details
* `pendingToolCalls` - Tool calls awaiting execution
* `pendingToolPermissionRequests` - Commands awaiting approval
* `pendingAskHumanRequests` - Questions awaiting user response
* `subflowStates` - State for agent-tool executions
* `sessionAllowedCommands` - Commands approved for session

## Execution Flow

1. **Load agent** - Parse Markdown file and extract configuration
2. **Build tools** - Map tool definitions to executable functions
3. **Create provider** - Initialize LLM provider and model
4. **Run loop** - Execute agent logic:
   * Execute pending tool calls
   * Check for pending permissions or ask-human requests
   * Dequeue user messages
   * Run LLM turn with current message history
   * Process tool calls from LLM response
   * Repeat until completion

Location: `apps/x/packages/core/src/agents/runtime.ts:672`

## Skill System

Skills provide specialized guidance for specific tasks. Agents can load skills on-demand to access domain-specific instructions.

```typescript Available Skills theme={null}
// Load a skill
const skill = resolveSkill("web-search");

// Available skills:
// - web-search
// - slack
// - background-agents
// - builtin-tools
// - mcp-integration
// - doc-collab
// - draft-emails
// - meeting-prep
// - organize-files
// - create-presentations
// - deletion-guardrails
```

```typescript Skill Catalog theme={null}
import { skillCatalog } from "@x/core/skills";

// Markdown catalog of all skills
console.log(skillCatalog);
```

Location: `apps/x/packages/core/src/application/assistant/skills/index.ts:1`

See [Skills](/platform/agents/skills) for details.

## Security

### Command Filtering

Commands executed via `executeCommand` are filtered through `~/.rowboat/config/security.json`:

```json theme={null}
{
  "allowedCommands": [
    "git",
    "npm",
    "node",
    "curl"
  ]
}
```

Blocked commands return exit code 126.

Location: `apps/x/packages/core/src/application/lib/command-executor.ts:15`

### Permission Requests

Certain operations require user approval:

* **Tool permissions** - Approval for executing potentially dangerous commands
* **Ask human** - Explicit user input during execution
* **Session scope** - Approve command for entire session

Location: `apps/x/packages/core/src/agents/runtime.ts:627`

## Next Steps

> **[Runtime Architecture](/platform/agents/runtime)**
>
> Explore the agent runtime implementation

> **[Background Agents](/platform/agents/background-agents)**
>
> Learn about scheduled agent execution

> **[Skills](/platform/agents/skills)**
>
> Discover available skills and how to use them


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.