---
title: "Documentation"
description: "The FastAgent documentation map: quickstart, configuration, embedding, channels, deployment, and reference for serving agent directories as live services."
image: "https://fastagent.sh/social-preview.png"
---

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

# Documentation

FastAgent is the serving layer for local agent directories. It takes a directory out of the terminal and serves it as a live service: embedded in your app, connected to Telegram or Slack, handling GitHub/webhook events, exposed as an API endpoint, or running behind your own channel. `persona.md` is recommended for identity (an `AGENTS.md` is project context the agent reads), but the directory is the unit.

## Recommended path

1. Read the [Overview](/docs/overview/) to understand the shape.
2. Run the [Quickstart](/docs/quickstart/) to create and serve a workspace.
3. Use [Configuration](/docs/configuration/) when choosing models, auth, ports, sessions, tools, and channels.
4. Pick the integration path you need: [Embedding](/docs/embedding/) or [Channels](/docs/channels/).
5. Ship the directory with [Deploy](/docs/deploy/) when the agent should run on a host.

Using a coding agent? Give it the repository's [`ai-start.md`](/docs/ai-start/) for an AI-guided setup path.

## Guides

| Goal | Read |
|---|---|
| Understand what FastAgent is | [Overview](/docs/overview/) |
| Understand the design choices and non-goals | [Design principles](/docs/principles/) |
| Scaffold, run locally, add a tool, and start | [Quickstart](/docs/quickstart/) |
| Configure model, auth, ports, sessions, tools, and channels | [Configuration](/docs/configuration/) |
| Embed an agent in an existing app or route | [Embedding](/docs/embedding/) |
| Connect GitHub, Telegram, Slack, or another channel | [Channels](/docs/channels/) |
| Run the agent on a cron, or let it wake itself | [Quickstart §8](/docs/quickstart/#8-run-on-a-clock), [API reference](/docs/api-reference/#schedule-authoring) |
| Ship the agent to a host | [Deploy](/docs/deploy/) |

## Channel guides

| Goal | Read |
|---|---|
| Use GitHub webhooks | [GitHub channel](/docs/github/) |
| Use a Telegram bot | [Telegram channel](/docs/telegram/) |
| Use a Slack app | [Slack channel](/docs/slack/) |
| Use Feishu or its Lark compatibility profile | [Feishu channel (Lark compatibility)](/docs/feishu/) |
| Build a custom channel adapter | [Channel development](/docs/channel-development/) |

## Reference

| Goal | Read |
|---|---|
| Use the CLI | [CLI reference](/docs/cli/) |
| Look up TypeScript exports | [API reference](/docs/api-reference/) |
| Understand the event stream contract | [Agent Handler SPEC](/docs/spec/) |
| Fix common setup/runtime issues | [Troubleshooting](/docs/troubleshooting/) |

## Core concepts

- **The directory is the agent.** Runtime behavior comes from the workspace: optional `persona.md` (identity), `skills/`, `tools/`, `channels/`, `schedules/`, `AGENTS.md` (project context), and markdown context.
- **`invoke` is the contract.** Every channel or host drives an `Agent` through `invoke(scope, prompt) => AsyncIterable<AgentEvent>`.
- **Channels are adapters.** A channel receives external events (HTTP, GitHub, Telegram, Slack, …), maps them to one or more agent turns, and returns host-specific responses.
- **Hosts own runtime state.** Sessions, credentials, execution environment, and locking are runtime concerns, not part of the agent definition.
- **Small core, typed edges.** FastAgent uses a small callable contract, app-level composition, and validation at the boundaries.

## Maintainer notes

These are not required to use FastAgent, but they explain public architecture decisions and tradeoffs:

| Document | Purpose |
|---|---|
| [Design notes](/docs/design/) | What belongs in public design docs |
| [Core design](/docs/design/core/) | pi reference implementation, assembly ladder, sessions, auth, and deployment model |
| [Session control plane](/docs/design/session-control/) | Serving extension beside `invoke`: observation plane shipped; control plane (dispatch) proposed |

For contribution workflow, see [../CONTRIBUTING.md](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md).

Upstream: https://github.com/fastagent-sh/fastagent/edit/main/docs/README.md