fastagent

FastAgent is a runtime and adapter layer that turns a local agent directory into a real-time service. Its starting point is a common pain point: coding agents have made it cheap to generate useful agent directories, but local agents usually live only in the terminal, while real services need to receive webhooks, join Telegram, serve product users, and expose stable APIs. FastAgent is the bridge between local agent directories and online services.

1. Purpose FastAgent is not a new agent-authoring DSL, nor does it replace your existing definitions and project layout. You keep your existing agent definitions and project directory, and FastAgent provides a publishing runtime and adapters around them. It can serve the same agent as a Telegram bot, Slack app, Feishu/Lark bot, HTTP/SSE interface, or custom adapter, with support for verified webhooks, streaming replies, and group awareness.

2. Main capabilities

3. Directory as agent: an agent is a directory containing Markdown instructions, reusable Skills, and TypeScript tools, and it is still a file you can view, edit, and commit. The project declares content alongside the agent for its use, and the agent can read and modify it, but this content does not become part of the agent definition.

4. Channels: the same agent can be served as a Telegram bot, Slack app, Feishu/Lark bot, HTTP/SSE endpoint, or your own adapter.

5. Models, tools, and skills: connect to any model provider via OAuth or API key (OpenAI, Anthropic, Google, etc.); discover typed tools at any depth from tools/ (named via defineTool and validated by Zod); Agent Skills are loaded on demand. It is built on the open-source pi harness.

6. Application embedding: mount the agent into a Next / Astro / Hono / Bun / Node route with a single handler, or call invoke like a function in your own code. Authentication, databases, and infrastructure remain yours.

7. Deployment: there is no application build step; the directory is the deployable unit. fastagent deploy docker|fly|railway|agentcore generates containers, target configurations, and runbook (--run can drive it to completion). Local Docker gets the user's own Compose and persistent state; the optional --tunnel adds a temporary Quick Tunnel service for webhook channels; AWS Bedrock AgentCore gets a single-stack CloudFormation topology (webhooks via a forwarder Lambda, scheduled via EventBridge). Persistent ingress remains your responsibility.

8. Design Philosophy FastAgent is built around a small service contract, application-owned runtime concerns, typed boundaries, and composable adapters. Small service core: invoke decouples channels, agents, harnesses, and infrastructure. Application-owned runtime: it does not take over your auth, database, routing, or deployment. Typed boundaries: typed tools, explicit events, boundary validation. Agent-native form: a directory is the deployable unit, and each channel drives the same contract.

FastAgent deliberately remains a small service layer and does not decide your tech stack for you: there is no platform to migrate into (no dashboard, no control plane, no deployment target runtime), no new format or DSL (it consumes existing standards such as AGENTS.md, Agent Skills, TypeScript tools, HTTP/SSE), no workflow engine (the agent decides the steps itself, and deterministic multi-step orchestration can call invoke from your own queue or workflow), and no model or cloud lock-in (the Agent Handler contract is harness-agnostic, the built-in pi is a harness, and you can bring your own harness while all channels continue to work).

1. Usage Requires Node >= 22.19 (the lower bound is inherited from the pi harness and undici), and it can also run under Bun (smoke-tested in CI on Bun 1.3; its native fetch replaces the undici path). The npm package provides compiled JavaScript and type declarations.

2. Working with coding agents: you can paste the following into Claude Code, Codex, Cursor, or another coding agent: Read https://fastagent.sh/start.md and build an agent in this project.

3. Starting point: begin with the agent development guide, the authoring entry point for humans and coding agents, covering responsibilities, TypeScript tools, validation, channels, scheduling, and deployment. The repository's AGENTS.md is aimed at maintainers.

4. Local testing and local service: you can send local test turns, or run it as a production-style local service. FastAgent has no build step: the agent folder is the deployable unit.

5. Embedding in an application: when no directory is needed, it can be assembled from typed parts. Public API surface: the root export contains only the supported surface. Provider and ProviderAuth are exported as types (because options mention them), and the factory createProvider that builds them comes from @earendil-works/pi-ai; when registering a custom provider, you need to add it as a direct dependency. Subpath entries (./package.json also has exports for tools that read the version):

• @fastagent-sh/fastagent/core — harness-agnostic protocol, collect, the agent API as a handler (createAgentHandler) and connectAgent as a client, the channel suite, and scheduling. There are no packages other than Effect, and no Node built-in modules, enforced by tests.
• @fastagent-sh/fastagent/node — the harness-agnostic parts that require the Node runtime: mountAgentService (assembly), serveNode / nodeListener (node:http ↔ Fetch binding).
• @fastagent-sh/fastagent/pi — the pi reference implementation.
• @fastagent-sh/fastagent/telegram — the Telegram bot channel.
• @fastagent-sh/fastagent/slack — the Slack Events API bot channel.
• @fastagent-sh/fastagent/feishu — the canonical Feishu bot channel(Feishu, open.feishu.cn).
• @fastagent-sh/fastagent/lark — Lark international compatibility configuration based on the Feishu engine.

V. Applicable Scenarios Developers who want to quickly publish a local agent directory as a Telegram/Slack/Feishu bot, HTTP/SSE interface, or service within their own application; teams that need to embed agents into existing Next/Astro/Hono/Bun/Node applications without migrating their tech stack; scenarios where the same agent definition serves multiple channels while retaining their own authentication, database, and deployment control.

VI. Limitations and Current Status FastAgent is pre-1.0. The stable design center is the Agent Handler contract in docs/SPEC.md; before 1.0 the package API may still tighten, and important changes are recorded in GitHub Releases. The design leaves room for features that have not yet become full product capabilities: regarding durable execution, turns already accepted by Telegram, Slack, and Feishu/Lark are currently replayed at least once, and general durability and exactly-once execution remain future backend work; regarding sandboxed execution, all seven coding tools, project context, channels, and author-written tools/ directly touch the local process, and sandboxing around the complete agent process is future work; regarding observability export, there are currently leveled logs and per-turn tracing, but no OpenTelemetry exporter; regarding harness binding and channels, pi is the built-in harness, other harnesses can implement the Agent contract, and community channels can use the channel kit; regarding deployment targets, local Docker, Fly, Railway, and AWS Bedrock AgentCore are currently provided, and the generated container is a portable path for other hosts.

The license is MIT. Runtime dependencies use permissive open source licenses and are installed as separate npm packages; the built-in scaffolding writing-great-skills skill comes from mattpocock/skills and carries its own license. The built-in harness is pi (pi.dev), which provides the agent loop, multi-provider LLM APIs, and the interactive TUI driven by fastagent chat. The project also depends on zod, undici, chokidar, giget, @clack/prompts, ignore, and octokit/webhooks.