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
- Start with Develop an Agent with FastAgent, the canonical authoring guide for humans and coding agents. It covers responsibilities, TypeScript, verification, channels, scheduling, and deployment.
- Use Overview for the product shape or Quickstart for a short first run.
- 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.
Give a coding agent the same ai-start.md. The repository’s AGENTS.md and the maintainer notes below describe FastAgent development, not how to author an agent.
Guides
| Goal | Read |
|---|---|
| Develop an agent from responsibilities through verified deployment | Agent development guide |
| 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 agent directory: 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 |
| Participant model | When a chat channel speaks, where it answers, and what it remembers — the authority behind Feishu/Lark and Slack routing |
| Session control plane | Serving extension beside invoke: observe a session, act on its run, set its properties, and manage the deployment’s sessions |
For contribution workflow, see ../CONTRIBUTING.md.