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
- Read the Overview to understand the shape.
- Run the Quickstart to create and serve a workspace.
- Use Configuration when choosing models, auth, ports, sessions, tools, and channels.
- Pick the integration path you need: Embedding or Channels.
- Ship the directory with Deploy when the agent should run on a host.
Using a coding agent? Give it the repository’s ai-start.md for an AI-guided setup path.
Guides
| Goal | Read |
|---|---|
| Understand what FastAgent is | Overview |
| Understand the design choices and non-goals | Design principles |
| Scaffold, run locally, add a tool, and start | Quickstart |
| Configure model, auth, ports, sessions, tools, and channels | Configuration |
| Embed an agent in an existing app or route | Embedding |
| Connect GitHub, Telegram, Slack, or another channel | Channels |
| Run the agent on a cron, or let it wake itself | Quickstart §8, API reference |
| Ship the agent to a host | Deploy |
Channel guides
| Goal | Read |
|---|---|
| Use GitHub webhooks | GitHub channel |
| Use a Telegram bot | Telegram channel |
| Use a Slack app | Slack channel |
| Use Feishu or its Lark compatibility profile | Feishu channel (Lark compatibility) |
| Build a custom channel adapter | Channel development |
Reference
| Goal | Read |
|---|---|
| Use the CLI | CLI reference |
| Look up TypeScript exports | API reference |
| Understand the event stream contract | Agent Handler SPEC |
| Fix common setup/runtime issues | 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. invokeis the contract. Every channel or host drives anAgentthroughinvoke(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 | What belongs in public design docs |
| Core design | pi reference implementation, assembly ladder, sessions, auth, and deployment model |
| Session control plane | Serving extension beside invoke: observation plane shipped; control plane (dispatch) proposed |
For contribution workflow, see ../CONTRIBUTING.md.