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 real 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 real 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, 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. Like Flask/FastAPI for agents: FastAgent never owns your framework. Mount the agent in your Next / Astro / Hono / Bun / Node route with one handler — your auth, your database, your host.
• Deploy anywhere. Run the directory directly — no build step; fastagent deploy fly|railway generates the host config + a runbook and hands off (--run drives the deploy to completion). The generated container also runs on other Docker hosts.

Using a coding agent? Give it docs/ai-start.md for an AI-guided setup path.

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, engines, and hosts.
• 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 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 host, 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 to any host.
• 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 engine-neutral, with pi as the reference implementation; another engine can implement the same Agent contract without changing channels.

Install

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 reference engine 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.

Subpath exports:

• @fastagent-sh/fastagent/core — engine-neutral contract, consumption helpers, channel/host kit, schedules;
• @fastagent-sh/fastagent/pi — the pi reference implementation;
• @fastagent-sh/fastagent/github — GitHub webhook channel;
• @fastagent-sh/fastagent/telegram — Telegram bot channel.

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 accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
• Sandboxed execution — ExecutionEnv is an assembly seam, but the pi coding tools and project-context loader are still local; a complete sandbox adapter is future work.
• Observability export — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
• More reference bindings and channels — pi is the reference implementation; another engine can implement the Agent contract, and community channels can use the channel kit.
• More deploy targets — Fly and Railway 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.

Project

• Contributing
• Security policy

Acknowledgements

FastAgent stands on open source. The reference implementation is built on pi (pi.dev) — its agent harness, 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.

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.