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, GitHub/webhook events, an API endpoint, or 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 support, GitHub PR review, webhook handler, API endpoint, 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 Telegram, serve product users, and expose stable APIs.

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

Features

• Vibe first — a directory is an agent. Point FastAgent at the AGENTS.md + skills/ you already vibed in a coding agent. Markdown instructions, reusable skills, and TypeScript tools stay as files you inspect, edit, and commit — no new DSL, no framework rewrite.
• Channels. Serve the same agent as a GitHub PR reviewer, a Telegram bot, a Feishu or Lark bot, an HTTP/SSE endpoint, or your own adapter: verified webhooks, streaming replies, group-aware.
• Models, tools & skills. Any model provider (OpenAI, Anthropic, Google, …) via OAuth or API key; typed tools discovered from tools/ (the filename is the name, Zod-validated); Agent Skills loaded on demand. Built on the open-source pi harness.
• App embedding — your stack, we plug in. Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler, or call invoke like any function from your own code — your auth, your database, your infra. 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; optional --tunnel adds an ephemeral Quick Tunnel service for webhook channels; 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.

• Small serving core — invoke decouples channels, agents, harnesses, and infra.
• 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 channels drive the same contract.

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 tools, HTTP/SSE — 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, call invoke from your own queue or workflow.
• No model or cloud lock-in. The Agent Handler contract is harness-neutral (the SPEC says engine — same seam), with pi as the built-in harness; bring your own harness and every channel keeps working unchanged.

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 >= 22.19 (the floor is inherited from the pi harness and undici), and also runs under Bun (smoke-tested in CI on Bun 1.3; 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 a local test turn:

curl -N -X POST localhost:8787/invoke \
  -H 'content-type: application/json' \
  -d '{"session":"s1","text":"hello"}'

For production-style local serving:

fastagent start

There is no FastAgent build step: the directory is the agent.

Embed in an app

import { createInvokeHandler, createPiAgentFromDefinition } from "@fastagent-sh/fastagent";

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

export const POST = createInvokeHandler(agent); // Fetch-shaped handler

No directory? Assemble from typed parts:

import { createPiAgent, defineTool, z } from "@fastagent-sh/fastagent";

const lookupOrder = defineTool({
  name: "lookup-order",
  description: "Look up an order by id.",
  input: z.object({ orderId: z.string() }),
  async execute({ orderId }) {
    return await db.find(orderId);
  },
});

const agent = createPiAgent({
  model: "openai-codex/gpt-5.5",
  instructions: "You are a support assistant. Use lookup-order for order questions.",
  tools: [lookupOrder],
});

Documentation

Public API surface & stability

The root export intentionally contains the supported surface only.

Engine-neutral and runtime-neutral are different properties, and the entries are layered by them — each layer drops one, and every layer’s dependency list is asserted in CI:

Provider and ProviderAuth are exported as types because our options name them; the factory that builds one, createProvider, comes from @earendil-works/pi-ai — add it as a direct dependency when you register a custom provider.

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

• @fastagent-sh/fastagent/core — engine-neutral contract, consumption helpers, channel kit, schedules, and the session-control clients (connectSessionControl, connectAgent). Zero third-party dependencies, enforced by test;
• @fastagent-sh/fastagent/node — the engine-neutral pieces that need a Node runtime: mountAgentService (the assembly), serveNode / nodeListener (the node:http ↔ Fetch binding);
• @fastagent-sh/fastagent/session — the engine-neutral session-control contract (types and error codes);
• @fastagent-sh/fastagent/pi — the pi reference implementation;
• @fastagent-sh/fastagent/github — GitHub webhook channel;
• @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) + reusable SPEC conformance
docs/    user docs, SPEC, and maintainer design notes

Single package, likely long-term; subpath exports (not sibling packages) are the module boundary. A packages/ workspace split is deliberately deferred until a second published artifact with independent dependencies/versioning actually exists.

Status

FastAgent is pre-1.0. The stable design center is the Agent Handler contract 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 neutral contract leaves room for capabilities that are not complete product features yet:

• Durable execution: Telegram, Slack, and Feishu/Lark accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
• Sandboxed execution — all seven coding tools, ② project context, channels, and author-written tools/ reach the local process directly; a sandbox around the complete agent process is future work.
• Observability export — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
• More harness bindings and channels — pi is the built-in harness; another harness can implement the Agent contract, and community channels can use the channel kit.
• 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 built-in harness is pi (pi.dev) — its agent loop, multi-provider LLM API, and the interactive TUI that fastagent chat drives.

It also depends on, and is grateful to, zod, undici, chokidar, giget, @clack/prompts, ignore, and octokit/webhooks.

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.