---
title: "Agents"
description: "Core agent concepts in Fabro"
---

An agent in Fabro is an LLM session with access to tools. When a workflow reaches an agent node, Fabro creates a session, sends the prompt and prior context to the model, and lets the agent work autonomously — reading files, running commands, editing code, spawning sub-agents — until it decides the task is complete.

## The agent loop

Each agent turn follows the same cycle:

1. **Send** — Fabro sends the conversation history (system prompt, prior messages, tool results) to the LLM
2. **Receive** — The model responds with text, tool calls, or both
3. **Execute** — Fabro executes any tool calls in the sandbox and appends the results to the conversation
4. **Repeat** — If the model made tool calls, go back to step 1. If it responded with only text, the agent is done.

This loop continues until the model stops calling tools, indicating it considers the task complete. Fabro also enforces guardrails: token budgets, turn limits, and loop detection to prevent runaway agents.

## Backends

Every agent node uses a **backend** that determines how Fabro interacts with the LLM. There are two options:

### API backend (default)

Fabro manages the agent loop directly — it calls the LLM provider's API, executes built-in tools in the sandbox, and tracks file changes via tool call events. This is the default and supports the full feature set:

- [Session caching](/execution/context) via `fidelity="full"` + `thread_id`
- [Sub-agents](/agents/subagents)
- Provider failover
- All [built-in tools](/agents/tools) and [MCP](/agents/mcp) integrations

### CLI backend

Fabro delegates execution to an external coding assistant CLI. The CLI tool manages its own tool loop internally — Fabro sends the prompt, waits for the CLI to finish, and tracks file changes via `git diff` before and after execution.

The CLI is selected automatically based on the node's provider:

| Provider | CLI tool |
|---|---|
| Anthropic | `claude` |
| OpenAI | `codex` |
| Gemini | `gemini` |

Set the CLI backend on a node with `backend="cli"` or via a [model stylesheet](/workflows/stylesheets):

```dot
implement [label="Implement", backend="cli"]
```

```
// Stylesheet
* { backend: cli; }
```

### Comparison

| Capability | API backend | CLI backend |
|---|---|---|
| Tools | Fabro built-in tools + MCP | CLI's own tool set |
| Session caching | Supported (`fidelity` + `thread_id`) | Not supported |
| Sub-agents | Supported | Not supported |
| Provider failover | Supported | Not supported |
| File tracking | Tool call events | `git diff` before/after |

### When to use the CLI backend

- **CLI-specific tools** — leverage tool implementations built into a specific CLI (e.g. Claude Code's computer use, Codex's sandboxed execution)
- **CLI-only models** — use models that are only available through a CLI tool, not via API
- **Existing workflows** — integrate a CLI tool you already depend on without rewriting its configuration

## Tools

Agents have access to a set of built-in tools for interacting with the codebase and environment:

| Tool | Description |
|---|---|
| `shell` | Run shell commands (bash) |
| `read_file` | Read file contents with optional offset and limit |
| `write_file` | Create or overwrite a file |
| `edit_file` | Make targeted edits to an existing file |
| `grep` | Search file contents with regex patterns |
| `glob` | Find files by name pattern |
| `web_search` | Search the web |
| `web_fetch` | Fetch and summarize a URL |

Additional tools can be added via [MCP servers](/agents/mcp) for integrations like databases, APIs, or custom services.

See [Tools](/agents/tools) for the full reference.

## Prompts

The agent's behavior is shaped by its prompt — the task instructions set in the `prompt` attribute of the workflow node. Prompts can be inline strings or references to external Markdown files:

```dot
// Inline prompt
plan [label="Plan", prompt="Analyze the codebase and write a step-by-step plan."]

// External file reference
simplify [label="Simplify", prompt="@prompts/simplify.md"]
```

Fabro also injects a system prompt with context about the workflow goal, prior stage outputs, available tools, and the agent's role. See [Prompts](/agents/prompts) for details.

## Sub-agents

An agent can spawn **sub-agents** to delegate subtasks. Sub-agents run in their own session with their own tool access, and return results to the parent. This is useful for parallelizing research, isolating risky operations, or breaking complex tasks into manageable pieces.

See [Sub-agents](/agents/subagents) for details.

## Skills

Skills are reusable prompt templates that extend an agent's capabilities for common tasks — code review, test writing, refactoring, and more. They're discovered automatically from the project and can be invoked by the agent during its session.

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

## Hooks

Hooks are shell commands that run in response to agent lifecycle events (e.g. before a tool executes, after a stage completes). They enable custom validation, notifications, and guardrails without modifying the workflow graph.

See [Hooks](/agents/hooks) for details.

## Further reading

<Columns cols={2}>
  <Card title="Prompts" icon="message" href="/agents/prompts">
    How prompts are constructed and injected.
  </Card>
  <Card title="Tools" icon="wrench" href="/agents/tools">
    Built-in tools and custom tool registration.
  </Card>
  <Card title="MCP" icon="plug" href="/agents/mcp">
    Extend agents with Model Context Protocol servers.
  </Card>
  <Card title="Sub-agents" icon="users" href="/agents/subagents">
    Delegate subtasks to child agent sessions.
  </Card>
</Columns>