fastagent-sh/fastagent

Built on

— the agent harness & multi-provider LLM API under the hood

A file-defined agent directory can become a live service. FastAgent takes it out of the terminal and serves it in your Next/Astro app, Telegram, Slack, Feishu, on a clock, or behind your own channel.

Leave the terminal. Become a live service.

• Add it to your app — one route, your auth, your database, your host.
• Run it as a live service — Telegram, Slack or Feishu bot, webhook handler, schedule, or custom channel.

FastAgent is not a new agent-authoring DSL. You bring the existing definition and project layout; FastAgent provides the serving runtime and adapters around it.

Why FastAgent

Coding agents made it cheap to vibe useful agent directories. The hard part is the next step: local agents live in terminals, but real services receive webhooks, join chats, run on a clock, and keep their conversations across restarts.

FastAgent is the missing bridge from local agent directory to live service.

Features

• Vibe first — an agent is a directory of its own. A SYSTEM.md prompt, reusable skills, and TypeScript tools stay as files you inspect, edit, and commit — no new DSL, no framework rewrite. The projects it works on are declared beside it as its content, which it reads and changes but which never becomes part of its definition.
• Channels. Serve the same agent as a Telegram bot, a Slack app, a Feishu or Lark bot, or your own adapter: verified webhooks, streaming replies, group-aware.
• Durable by default. Every conversation lives in the instance’s storage, and an accepted message is answered after a restart. Built on the open-source pi durable harness.
• Models, tools & skills. Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key, plus your own providers in code; typed tools in src/tools/ (TypeBox-validated); Agent Skills loaded on demand.
• App embedding — your stack, we plug in. Open the agent in your own process and call it like any function, behind your auth, with your database and infra; mount its channels in your Next / Astro / Hono / Bun / Node app with one handler. FastAgent composes with your app, never owns it.
• Deploy anywhere. No application build step — the directory is the deployable unit. fastagent deploy docker|fly|railway|agentcore generates the container + target config and a runbook (--run drives it to completion). Local Docker gets user-owned Compose + durable state; AWS Bedrock AgentCore gets a one-stack CloudFormation topology (webhooks via a forwarder Lambda, schedules via EventBridge). Durable ingress remains yours.

Design philosophy

FastAgent is built around a small serving contract, app-owned runtime concerns, typed boundaries, and composable adapters.

• One API, in process and over HTTP — the Agent API is what every channel, schedule and app calls, and what a program calls a deployed agent with.
• App-owned runtime — no takeover of your auth, database, routes, or deployment.
• Typed edges — typed tools, explicit events, boundary validation.
• Agent-native shape — the directory is the deployable unit, and every check is a command a coding agent can run.

Read the Design principles for the full rationale.

What we didn’t build

FastAgent stays a small serving layer, so it never dictates your stack. Capabilities other agent frameworks bake into a platform, we leave to your app, your infra, or the agent itself — composed in, not locked in.

• No platform to move to. No dashboard, no control plane, no runtime you deploy into — run it locally, embed it in your app, or ship the directory anywhere.
• No new format or DSL. AGENTS.md, Agent Skills, TypeScript modules — FastAgent consumes the standards you already use instead of a parallel ecosystem.
• No workflow engine. The agent decides its own steps; for deterministic multi-step orchestration, send messages from your own queue or workflow.
• One key, no auth system. A served agent answers its channels, each of which verifies its platform, and, given FASTAGENT_API_KEY, the Agent API under /v1: one key for the whole instance, kept on a server, that keeps everyone but its customer out. Users, roles and per-session access are your app’s, in front of it.
• No model or cloud lock-in. Any provider pi-ai supports, or your own; any host that runs a container.

Install

Start with the agent development guide, the authoring entry point for both humans and coding agents. It covers responsibilities, TypeScript tools, verification, channels, scheduling, and deployment. FastAgent’s repository AGENTS.md is for maintainers.

To work with Claude Code, Codex, Cursor, or another coding agent, paste:

Read https://fastagent.sh/start.md and build an agent in this project.

For humans:

npm i -g @fastagent-sh/fastagent   # CLI: fastagent init/dev/start/...
npm i @fastagent-sh/fastagent      # library API for embedding or code tools

Requires Node >= 24.15 or Bun >= 1.4, both set by the agent’s storage, node:sqlite: Node stops calling it experimental in 24.15, and Bun ships it from 1.4 (smoke-tested in CI on 1.4.0; its native fetch replaces the undici path). The npm package ships compiled JavaScript and type declarations.

Quickstart

fastagent init my-agent
cd my-agent
fastagent dev

Then send it a message:

fastagent invoke "hello"

For production-style local serving:

fastagent start

There is no FastAgent build step: the agent folder is the deployable unit.

Embed in an app

import { openAgent } from "@fastagent-sh/fastagent";

const agent = await openAgent("./agent", { model: "openai/gpt-5.5" });

const session = await agent.sessions.create();
for await (const event of agent.messages.stream({ sessionId: session.id, content: "hi" })) {
  if (event.type === "delta" && event.channel === "text") render(event.text);
}

await agent.serve() adds the agent’s channels and schedules to your app: a Fetch handler for its webhooks, mounted where your framework routes them, or a server of its own (listen) (Embedding). Served with a key (FASTAGENT_API_KEY for start), the same API is reachable over HTTP under /v1, and another program calls it with connectAgent(url, { apiKey }) from @fastagent-sh/fastagent/client as it would the opened agent.

Documentation

Public API surface & stability

The package exports the supported surface only, from one entry per kind of user, and names every export (no export *), which CI asserts:

A tool or an extension is pi-durable’s own (defineTool, defineExtension from @earendil-works/pi-durable), and a custom provider is pi-ai’s (createProvider from @earendil-works/pi-ai): init adds both packages to the agent.

Entry points (./package.json is also exported, for tools that read the version):

• @fastagent-sh/fastagent — the Agent API, openAgent, what a host embedding agents needs, and what an author writes;
• @fastagent-sh/fastagent/client — connectAgent, the Agent API over HTTP, for a program anywhere fetch runs;
• @fastagent-sh/fastagent/telegram — Telegram bot channel;
• @fastagent-sh/fastagent/slack — Slack Events API bot channel;
• @fastagent-sh/fastagent/feishu — canonical Feishu bot channel (飞书, open.feishu.cn);
• @fastagent-sh/fastagent/lark — Lark-international compatibility profile over the Feishu engine.

Repository layout

src/     the npm package: CLI, library API, reference implementation
test/    vitest suite (faux models by default) + the Agent API's conformance suite
docs/    user docs, SPEC, and maintainer design notes

One package; subpath exports are the module boundary.

Status

FastAgent is pre-1.0. The stable design center is the Agent API in docs/SPEC.md; the package API may still tighten before 1.0. Notable changes are recorded in the GitHub Releases.

Designed for more

The Agent API leaves room for capabilities that are not complete product features yet:

• Scale-out: one process holds an instance’s storage today; spreading one instance over several processes is future work.
• Sandboxed execution — the coding tools, channels, and author-written code reach the local process directly; a sandbox around the complete agent process is future work.
• Observability export — leveled logs exist today; an OpenTelemetry exporter does not.
• More channels — community channels can use the channel kit. External tools can also use MCP servers.
• More deploy targets — local Docker, Fly, Railway, and AWS Bedrock AgentCore ship today; the generated container is the portable path for other hosts.

See Contributing if one of these is the problem you want to work on.

☁️ Prefer these managed? FastAgent Cloud will run your agents with multi-instance durability, scale-to-zero, and observability built in — and self-hosting stays free forever. Join the waitlist →

Project

• Contributing
• Security policy

Acknowledgements

FastAgent stands on open source. The harness is pi (pi.dev) — pi-durable’s durable agent loop and pi-ai’s multi-provider LLM API.

It also depends on, and is grateful to, Effect, undici, chokidar, giget, @clack/prompts, ignore, and croner.

The scaffolded writing-great-skills skill is vendored from mattpocock/skills, with its license included.

---

FastAgent is built in the open. If it saves you from rewriting an agent into yet another framework, give it a ⭐ — it’s the fastest way to help other devs find it.

License

MIT. Runtime dependencies use permissive open-source licenses and are installed as separate npm packages; the vendored writing-great-skills scaffold includes its own license.