Haiku Bot

You are Haiku Bot. Rules:

1. When asked for a poem, always answer with a haiku (5-7-5).
2. Sign every reply with "— haiku-bot".

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

For agents — paste this into Claude Code, Codex, Cursor, or any coding agent that reads the web:

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

Document	Purpose
Documentation index	Documentation map
Quickstart	Scaffold, run, add a tool, and start
Configuration	Configure model, auth, ports, sessions, tools, and channels
Design principles	Design choices, core primitives, and non-goals
CLI reference	CLI commands and flags
Embedding	Use FastAgent as a library inside your own app
Channels	Add webhook/bot channels
Deploy	Ship the directory to Fly, Railway, or any Docker host
GitHub / Telegram / Slack / Feishu and Lark	First-party channel guides
Channel development	Build custom channel adapters
API reference	Public TypeScript API reference
Troubleshooting	Common setup/runtime issues
Agent Handler SPEC	Agent Handler protocol v0.1
Core design	Maintainer architecture notes

Public API surface & stability

The root export intentionally contains the supported surface only.

Area	Examples	Stability
Contract	Agent, AgentEvent, collect	Stable within SPEC v0.1
Channels/host	createInvokeHandler, nodeListener, serveNode, router, Routes	Reference implementation, pre-1.0
pi assembly	createPiAgentFromDir, createPiAgentFromDefinition, createPiAgent	Usable now, may tighten before 1.0
Tool/channel authoring	defineTool, z, loadTools, loadChannels, ChannelModule	Usable now, may tighten before 1.0
Injection ports	PiSessionStore, inMemorySessionStore, jsonlSessionStore, Lease, Provider, createProvider	Public because options reference them
Not exported	L0 harness adapter, pi harness factory, prompt/config internals	Internal modules; no compatibility promise

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;
• @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 — ExecutionEnv governs the default coding tools, but ② project context and author-written tools/ still reach the local process; a complete sandbox adapter 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.

---

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.