@fastagent-sh/fastagent 0.12.0 → 0.12.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +39 -35
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
<p align="center">
|
|
2
|
-
<a href="https://
|
|
2
|
+
<a href="https://fastagent.sh"><img src="https://raw.githubusercontent.com/fastagent-sh/fastagent/main/assets/hero.png" alt="FastAgent — Vibe first. Then FastAgent. An agent directory becomes a live service in your app, on GitHub, in Telegram, or any channel." width="860"></a>
|
|
3
3
|
</p>
|
|
4
4
|
|
|
5
5
|
[](https://github.com/fastagent-sh/fastagent/actions/workflows/ci.yml)
|
|
6
6
|
[](https://www.npmjs.com/package/@fastagent-sh/fastagent)
|
|
7
|
-
[](LICENSE)
|
|
7
|
+
[](https://github.com/fastagent-sh/fastagent/blob/main/LICENSE)
|
|
8
8
|
[](https://nodejs.org)
|
|
9
9
|
[](https://pi.dev)
|
|
10
10
|
|
|
@@ -16,7 +16,7 @@
|
|
|
16
16
|
|
|
17
17
|
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.
|
|
18
18
|
|
|
19
|
-
Leave the terminal. Become a
|
|
19
|
+
Leave the terminal. Become a live service.
|
|
20
20
|
|
|
21
21
|
- **Add it to your app** — one route, your auth, your database, your host.
|
|
22
22
|
- **Run it as a live service** — Telegram support, GitHub PR review, webhook handler, API endpoint, or custom channel.
|
|
@@ -24,53 +24,57 @@ Leave the terminal. Become a real service.
|
|
|
24
24
|
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.
|
|
25
25
|
|
|
26
26
|
<p align="center">
|
|
27
|
-
<img src="https://cdn.jsdelivr.net/gh/fastagent-sh/fastagent@main/assets/demo.svg" alt="
|
|
27
|
+
<img src="https://cdn.jsdelivr.net/gh/fastagent-sh/fastagent@main/assets/demo.svg" alt="Three acts in one terminal: a coding agent vibes a support agent into a directory; fastagent dev serves it live, answering a GitHub pull request, a Telegram message, and an HTTP invoke; fastagent deploy fly --run ships it to a live URL." width="860">
|
|
28
28
|
</p>
|
|
29
29
|
|
|
30
30
|
## Why FastAgent
|
|
31
31
|
|
|
32
32
|
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.
|
|
33
33
|
|
|
34
|
-
FastAgent is the missing bridge from local agent directory to
|
|
34
|
+
FastAgent is the missing bridge from local agent directory to live service.
|
|
35
35
|
|
|
36
36
|
## Features
|
|
37
37
|
|
|
38
38
|
- **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.
|
|
39
39
|
- **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.
|
|
40
40
|
- **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](https://github.com/earendil-works/pi) harness.
|
|
41
|
-
- **App embedding — your stack, we plug in.**
|
|
42
|
-
- **Deploy anywhere.**
|
|
43
|
-
|
|
44
|
-
Using a coding agent? Give it [`docs/ai-start.md`](docs/ai-start.md) for an AI-guided setup path.
|
|
41
|
+
- **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.
|
|
42
|
+
- **Deploy anywhere.** No build step — the directory is the deployable unit. `fastagent deploy fly|railway` generates the deploy config + a runbook (`--run` drives it to completion); idle agents scale to zero and resume in hundreds of milliseconds on the next webhook. The generated container runs on any Docker host.
|
|
45
43
|
|
|
46
44
|
## Design philosophy
|
|
47
45
|
|
|
48
46
|
FastAgent is built around a small serving contract, app-owned runtime concerns, typed boundaries, and composable adapters.
|
|
49
47
|
|
|
50
|
-
- **Small serving core** — `invoke` decouples channels, agents,
|
|
48
|
+
- **Small serving core** — `invoke` decouples channels, agents, harnesses, and infra.
|
|
51
49
|
- **App-owned runtime** — no takeover of your auth, database, routes, or deployment.
|
|
52
50
|
- **Typed edges** — typed tools, explicit events, boundary validation.
|
|
53
51
|
- **Agent-native shape** — the directory is the deployable unit, and channels drive the same contract.
|
|
54
52
|
|
|
55
|
-
Read [Design principles](docs/principles
|
|
53
|
+
Read the [Design principles](https://fastagent.sh/docs/principles/) for the full rationale.
|
|
56
54
|
|
|
57
55
|
## What we didn't build
|
|
58
56
|
|
|
59
|
-
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
|
|
57
|
+
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.
|
|
60
58
|
|
|
61
|
-
- **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
|
|
59
|
+
- **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.
|
|
62
60
|
- **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.
|
|
63
61
|
- **No workflow engine.** The agent decides its own steps; for deterministic multi-step orchestration, call `invoke` from your own queue or workflow.
|
|
64
|
-
- **No model or cloud lock-in.** The Agent Handler contract is
|
|
62
|
+
- **No model or cloud lock-in.** The Agent Handler contract is harness-neutral (the [SPEC](https://fastagent.sh/docs/spec/) says *engine* — same seam), with [pi](https://pi.dev) as the built-in harness; bring your own harness and every channel keeps working unchanged.
|
|
65
63
|
|
|
66
64
|
## Install
|
|
67
65
|
|
|
66
|
+
For agents — paste this into Claude Code, Codex, Cursor, or any coding agent that reads the web:
|
|
67
|
+
|
|
68
|
+
> Read https://fastagent.sh/start.md and build an agent in this project.
|
|
69
|
+
|
|
70
|
+
For humans:
|
|
71
|
+
|
|
68
72
|
```bash
|
|
69
73
|
npm i -g @fastagent-sh/fastagent # CLI: fastagent init/dev/start/...
|
|
70
74
|
npm i @fastagent-sh/fastagent # library API for embedding or code tools
|
|
71
75
|
```
|
|
72
76
|
|
|
73
|
-
Requires **Node >= 22.19** (the floor is inherited from the pi
|
|
77
|
+
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.
|
|
74
78
|
|
|
75
79
|
## Quickstart
|
|
76
80
|
|
|
@@ -133,20 +137,20 @@ const agent = createPiAgent({
|
|
|
133
137
|
|
|
134
138
|
| Document | Purpose |
|
|
135
139
|
|---|---|
|
|
136
|
-
| [
|
|
137
|
-
| [
|
|
138
|
-
| [
|
|
139
|
-
| [
|
|
140
|
-
| [
|
|
141
|
-
| [
|
|
142
|
-
| [
|
|
143
|
-
| [
|
|
144
|
-
| [
|
|
145
|
-
| [
|
|
146
|
-
| [
|
|
147
|
-
| [
|
|
148
|
-
| [
|
|
149
|
-
| [
|
|
140
|
+
| [Documentation index](https://fastagent.sh/docs/) | Documentation map |
|
|
141
|
+
| [Quickstart](https://fastagent.sh/docs/quickstart/) | Scaffold, run, add a tool, and start |
|
|
142
|
+
| [Configuration](https://fastagent.sh/docs/configuration/) | Configure model, auth, ports, sessions, tools, and channels |
|
|
143
|
+
| [Design principles](https://fastagent.sh/docs/principles/) | Design choices, core primitives, and non-goals |
|
|
144
|
+
| [CLI reference](https://fastagent.sh/docs/cli/) | CLI commands and flags |
|
|
145
|
+
| [Embedding](https://fastagent.sh/docs/embedding/) | Use FastAgent as a library inside your own app |
|
|
146
|
+
| [Channels](https://fastagent.sh/docs/channels/) | Add webhook/bot channels |
|
|
147
|
+
| [Deploy](https://fastagent.sh/docs/deploy/) | Ship the directory to Fly, Railway, or any Docker host |
|
|
148
|
+
| [GitHub](https://fastagent.sh/docs/github/) / [Telegram](https://fastagent.sh/docs/telegram/) | First-party channel guides |
|
|
149
|
+
| [Channel development](https://fastagent.sh/docs/channel-development/) | Build custom channel adapters |
|
|
150
|
+
| [API reference](https://fastagent.sh/docs/api-reference/) | Public TypeScript API reference |
|
|
151
|
+
| [Troubleshooting](https://fastagent.sh/docs/troubleshooting/) | Common setup/runtime issues |
|
|
152
|
+
| [Agent Handler SPEC](https://fastagent.sh/docs/spec/) | Agent Handler protocol v0.1 |
|
|
153
|
+
| [Core design](https://fastagent.sh/docs/design/core/) | Maintainer architecture notes |
|
|
150
154
|
|
|
151
155
|
## Public API surface & stability
|
|
152
156
|
|
|
@@ -191,19 +195,19 @@ The neutral contract leaves room for capabilities that are not complete product
|
|
|
191
195
|
- **Durable execution** — Telegram accepted turns replay at least once today; general durability and exactly-once execution remain future backend work.
|
|
192
196
|
- **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.
|
|
193
197
|
- **Observability export** — leveled logs and per-turn traces exist today; an OpenTelemetry exporter does not.
|
|
194
|
-
- **More
|
|
198
|
+
- **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.
|
|
195
199
|
- **More deploy targets** — Fly and Railway ship today; the generated container is the portable path for other hosts.
|
|
196
200
|
|
|
197
|
-
See [Contributing](CONTRIBUTING.md) if one of these is the problem you want to work on.
|
|
201
|
+
See [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md) if one of these is the problem you want to work on.
|
|
198
202
|
|
|
199
203
|
## Project
|
|
200
204
|
|
|
201
|
-
- [Contributing](CONTRIBUTING.md)
|
|
202
|
-
- [Security policy](SECURITY.md)
|
|
205
|
+
- [Contributing](https://github.com/fastagent-sh/fastagent/blob/main/CONTRIBUTING.md)
|
|
206
|
+
- [Security policy](https://github.com/fastagent-sh/fastagent/blob/main/SECURITY.md)
|
|
203
207
|
|
|
204
208
|
## Acknowledgements
|
|
205
209
|
|
|
206
|
-
FastAgent stands on open source. The
|
|
210
|
+
FastAgent stands on open source. The built-in harness is **[pi](https://github.com/earendil-works/pi)** ([pi.dev](https://pi.dev)) — its agent loop, multi-provider LLM API, and the interactive TUI that `fastagent chat` drives.
|
|
207
211
|
|
|
208
212
|
It also depends on, and is grateful to, [zod](https://github.com/colinhacks/zod), [undici](https://github.com/nodejs/undici), [chokidar](https://github.com/paulmillr/chokidar), [giget](https://github.com/unjs/giget), [@clack/prompts](https://github.com/bombshell-dev/clack), [ignore](https://github.com/kaelzhang/node-ignore), and [octokit/webhooks](https://github.com/octokit/webhooks).
|
|
209
213
|
|
|
@@ -211,4 +215,4 @@ The scaffolded `writing-great-skills` skill is vendored from [mattpocock/skills]
|
|
|
211
215
|
|
|
212
216
|
## License
|
|
213
217
|
|
|
214
|
-
[MIT](LICENSE). Runtime dependencies use permissive open-source licenses and are installed as separate npm packages; the vendored `writing-great-skills` scaffold includes its own license.
|
|
218
|
+
[MIT](https://github.com/fastagent-sh/fastagent/blob/main/LICENSE). Runtime dependencies use permissive open-source licenses and are installed as separate npm packages; the vendored `writing-great-skills` scaffold includes its own license.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fastagent-sh/fastagent",
|
|
3
|
-
"version": "0.12.
|
|
4
|
-
"description": "Vibe first. Then FastAgent: turn a local agent directory into a
|
|
3
|
+
"version": "0.12.1",
|
|
4
|
+
"description": "Vibe first. Then FastAgent: turn a local agent directory into a live service in your app, on GitHub, in Telegram, or behind any channel.",
|
|
5
5
|
"keywords": [
|
|
6
6
|
"agent",
|
|
7
7
|
"ai-agent",
|
|
@@ -15,7 +15,7 @@
|
|
|
15
15
|
],
|
|
16
16
|
"license": "MIT",
|
|
17
17
|
"author": "the fastagent authors (https://github.com/fastagent-sh/fastagent)",
|
|
18
|
-
"homepage": "https://
|
|
18
|
+
"homepage": "https://fastagent.sh",
|
|
19
19
|
"repository": {
|
|
20
20
|
"type": "git",
|
|
21
21
|
"url": "git+https://github.com/fastagent-sh/fastagent.git"
|
|
@@ -83,7 +83,7 @@
|
|
|
83
83
|
"@octokit/webhooks-methods": "^6.0.0",
|
|
84
84
|
"@octokit/webhooks-types": "^7.6.1",
|
|
85
85
|
"chokidar": "^5.0.0",
|
|
86
|
-
"croner": "^
|
|
86
|
+
"croner": "^10.0.1",
|
|
87
87
|
"giget": "^3.3.0",
|
|
88
88
|
"ignore": "^7.0.5",
|
|
89
89
|
"undici": "^8.6.0",
|
|
@@ -91,7 +91,7 @@
|
|
|
91
91
|
},
|
|
92
92
|
"devDependencies": {
|
|
93
93
|
"@biomejs/biome": "^2.5.2",
|
|
94
|
-
"typescript": "^
|
|
94
|
+
"typescript": "^7.0.2",
|
|
95
95
|
"vitest": "^4.1.9"
|
|
96
96
|
}
|
|
97
97
|
}
|