fastagent

# FastAgent

> FastAgent is the serving layer for local agent directories. It takes a directory out of the terminal and turns it into a running agent service: embedded in an app, connected to Telegram, Slack or Feishu, handling webhook events, exposed as an API endpoint, or running behind a custom channel. Harness-, model-, and infra-neutral (the Agent Handler SPEC calls the harness the *engine* — same seam); the built-in harness is pi.

Key facts:

- Install: `npm i -g @fastagent-sh/fastagent` (CLI) or `npm i @fastagent-sh/fastagent` (library). Requires Node >= 22.19 (also runs under Bun).
- The agent is a `fastagent/` folder in a project, whose parent is its workspace: optional `persona.md` (identity), `skills/`, `tools/`, `channels/`, `routines/` (cron triggers), markdown context, and `fastagent.config.ts`; the project's `AGENTS.md` is context. No framework rewrite, no build step.
- The contract is `invoke(scope, prompt) => AsyncIterable<AgentEvent>` (the Agent Handler SPEC).
- Core CLI: `fastagent init | info | models | login | dev | chat | invoke | tool | fire | schedule | start | add | deploy`.
- Channels: HTTP/SSE (default), Telegram, Slack, Feishu/Lark, plus custom adapters.

## Start here

- [Website](https://fastagent.sh/): project overview, install, and product paths.
- [AI-guided start](https://fastagent.sh/start.md): executable instructions for a coding agent.
- [Documentation index](https://fastagent.sh/docs/): the full documentation map.

## Guides

- [Overview](https://fastagent.sh/docs/overview/): what FastAgent is and is not.
- [Quickstart](https://fastagent.sh/docs/quickstart/): scaffold, run locally, add a tool, and start.
- [Configuration](https://fastagent.sh/docs/configuration/): model, auth, ports, sessions, tools, and channels.
- [CLI reference](https://fastagent.sh/docs/cli/): every command and flag.
- [Embedding](https://fastagent.sh/docs/embedding/): use FastAgent as a library inside your own app.
- [Channels](https://fastagent.sh/docs/channels/): add webhook/bot channels.
- [Telegram channel](https://fastagent.sh/docs/telegram/): Telegram bot.
- [Channel development](https://fastagent.sh/docs/channel-development/): build a custom channel adapter.
- [Deploy](https://fastagent.sh/docs/deploy/): ship the directory to Fly, Railway, or any Docker host.
- [Troubleshooting](https://fastagent.sh/docs/troubleshooting/): common setup/runtime issues.

## Reference

- [API reference](https://fastagent.sh/docs/api-reference/): public TypeScript exports.
- [Agent Handler SPEC](https://fastagent.sh/docs/spec/): the v0.1 protocol contract.
- [Design principles](https://fastagent.sh/docs/principles/): design choices, core primitives, and non-goals.

## Optional

- [Core design notes](https://fastagent.sh/docs/design/core/): pi reference implementation architecture.
- [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md): branch model, PR loop, and review tiers.
- [Security policy](https://github.com/fastagent-sh/fastagent/security/policy): how to report a vulnerability.