diff --git a/README.md b/README.md index 0fa3c7fc..18e81db9 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Perstack: An Agentic AI Runtime +# Perstack

npm version @@ -12,102 +12,111 @@ Discord

-**No coding. No setup. Just ask.** +Agentic software in production hits two walls. Build from scratch, and most of the code is plumbing — not prompts. Throw a frontier model at a monolithic agent, and it works but doesn't scale commercially. + +Perstack takes a third approach: purpose-specific micro-agents on value-tier models. Narrow tasks don't need Opus-level reasoning. Haiku is enough. And single-purpose prompts are easy to write. + +`create-expert` generates agent definitions in a `perstack.toml` file. `perstack` executes them on an event-sourced runtime. ```bash -npx create-expert "form an indie-game-dev team that builds high-quality 2D games for the browser" -npx perstack start indie-game-dev "Cyberpunk pixel-art beat 'em up for the browser" +npx create-expert "Form a team named ai-gaming to build a Bun-based CLI indie game playable on Bash for AI." +npx perstack start ai-gaming --model "haiku-4-5" "Make a Wizardry-like dungeon crawler." ``` -`create-expert` turns ideas into runnable agent definitions. The runtime inside `perstack` executes them. No magic — just a properly designed agentic system. +A game built with these commands: [demo-dungeon-crawler](https://github.com/perstack-ai/demo-dungeon-crawler). Play it via `npx perstack-demo-dungeon-crawler start`. Built entirely on Claude 4.5 Haiku. -## Under the Hood +## How it works -1. **`create-expert`** generates a `perstack.toml` — agent behavior defined in plain English. It iteratively tests and refines the definition for you until it actually works. -2. **`perstack start`** executes the agents defined in `perstack.toml` and streams their activity in real time. -3. **Both run on `@perstack/runtime`** — an event-sourced, checkpointed runtime for long-running agents. Resume, replay, or diff executions across model changes whenever you want. -4. **`@perstack/base`** gives agents real-world tools (files, shell, etc.) via MCP. -5. **Complex tasks?** Agents delegate to specialist experts in parallel. +`create-expert` generates a `perstack.toml` that defines a team of micro-agents. Each agent has a single responsibility and its own context window. Complex tasks are broken down and delegated to specialists. +```toml +[experts."ai-gaming"] +description = "Game development team lead" +instruction = "Coordinate the team to build a CLI dungeon crawler." +delegates = ["@ai-gaming/level-designer", "@ai-gaming/programmer", "@ai-gaming/tester"] -### What `create-expert` actually generates +[experts."@ai-gaming/level-designer"] +description = "Designs dungeon layouts and game mechanics" +instruction = "Design engaging dungeon levels, enemy encounters, and progression systems." -The indie-game-dev example above produces something like this: +[experts."@ai-gaming/programmer"] +description = "Implements the game in TypeScript" +instruction = "Write the game code using Bun, targeting terminal-based gameplay." -```toml -[experts."indie-game-dev"] -description = "Indie game development team lead" -instruction = "Coordinate the team to build a high-quality 2D browser game." -delegates = ["@indie-game-dev/game-designer", "@indie-game-dev/programmer", "@indie-game-dev/artist", "@indie-game-dev/qa-tester"] +[experts."@ai-gaming/tester"] +description = "Tests the game and reports bugs" +instruction = "Play-test the game, find bugs, and verify fixes." +``` -[experts."@indie-game-dev/game-designer"] -description = "Designs game mechanics and level structure" -instruction = "Design engaging gameplay systems and level progression." +`perstack start` executes the agents and streams activity in real time. `perstack run` does the same headless with JSON output, for integration into your own applications. -[experts."@indie-game-dev/programmer"] -description = "Implements the game in TypeScript" -instruction = "Write clean, performant game code using HTML5 Canvas." +## Runtime -[experts."@indie-game-dev/artist"] -description = "Creates pixel art assets" -instruction = "Produce consistent pixel art sprites, tilesets, and UI elements." +The runtime (`@perstack/runtime`) is event-sourced. Every execution produces a hierarchy of Jobs, Runs, and Checkpoints. -[experts."@indie-game-dev/qa-tester"] -description = "Tests and finds bugs" -instruction = "Play-test the game, report bugs, and verify fixes." -``` +- **Resume** from any checkpoint if an execution is interrupted. +- **Replay** executions across different models to compare behavior. +- **Inspect** execution history with `perstack log`. -Plain English. No SDK. No glue code. This file *is* the agent. +Each agent runs in isolation with its own context window and tools. Agents communicate through shared workspace files, not shared conversation history. -## Go Deeper +## Providers -| Topic | Link | -| :--- | :--- | -| Build your first agent | [Rapid Prototyping Guide](https://perstack.ai/guides/rapid-prototyping/) | -| Break complex agents into specialists | [Taming Prompt Sprawl](https://perstack.ai/guides/taming-prompt-sprawl/) | -| Give agents real-world tools via MCP | [Extending with Tools](https://perstack.ai/guides/extending-with-tools/) | -| Deploy to Docker, AWS, GCP, Cloudflare | [Deployment](https://perstack.ai/docs/operating-experts/deployment/) | -| Architecture and core concepts | [Understanding Perstack](https://perstack.ai/docs/understanding-perstack/concept/) | -| Expert definitions in depth | [Making Experts](https://perstack.ai/docs/making-experts/) | -| CLI and runtime API reference | [References](https://perstack.ai/docs/references/cli/) | -| Examples: bug-finder, github-issue-bot, gmail-assistant | [examples/](./examples/) | +Anthropic, OpenAI, Azure OpenAI, Google, Vertex AI, DeepSeek, Ollama, Bedrock. -## Why Perstack? +## Tools -You've tried building AI agents. You know how it goes. +Agents access the outside world through MCP (Model Context Protocol). `@perstack/base` provides built-in tools: file read/write/edit, shell execution, image and PDF reading. -The prompts live in your application code. You can't test the agent without deploying the whole app. When you want to tweak behavior, it's a code change, a PR, a deploy. Domain experts who actually understand the task can't touch the prompts without a developer. And when something breaks, you're reading raw LLM logs trying to figure out which step went wrong. +Custom MCP servers can be added per agent in `perstack.toml`. -Perstack separates what the agent does from how your app works. +## Deployment -| You want to... | How Perstack handles it | -| :--- | :--- | -| **Test an agent idea in 30 seconds** | `npx create-expert "..."` — running agent, no app needed. | -| **Change agent behavior** | Ask `create-expert` again. It updates, tests, and refines on your request. | -| **Let non-developers tune the agent** | Edit the definition in `perstack.toml`. The definition is plain English. | -| **Debug a failed execution** | Describe the failure to `create-expert`. It can diagnose and fix Expert definitions. | -| **Run agents safely in production** | Each agent gets its own context window. | -| **Avoid LLM vendor lock-in** | Major providers are supported. Perstack is open-source. | +```dockerfile +FROM node:22-slim +WORKDIR /app +COPY perstack.toml perstack.lock . +RUN npm install -g perstack && perstack install +ENTRYPOINT ["perstack", "run", "--config", "/app/perstack.toml", "ai-gaming"] +``` -**Coming from other tools?** +The runtime can also be imported directly as a TypeScript library, so it works in Cloudflare Workers, Vercel, or any Node.js environment: -| If you use... | Perstack is for you if... | +```typescript +import { run } from "@perstack/runtime" + +const checkpoint = await run({ + setting: { + model: "claude-sonnet-4-5", + providerConfig: { providerName: "anthropic", apiKey: env.ANTHROPIC_API_KEY }, + expertKey: "ai-gaming", + input: { text: query }, + }, +}) +``` + +## Documentation + +| Topic | Link | | :--- | :--- | -| **LangGraph / PydanticAI** | You don't want to build your own tool integrations, agent loop, and error-feedback plumbing just to get a real agentic system running. | -| **CrewAI / AutoGen / Google ADK** | You want runtime-level isolation per agent, full event sourcing, and no shared process. | -| **OpenAI Agents SDK** | You want true multi-provider — not Response API with a compatibility layer on top. | -| **Mastra / Vercel AI SDK** | You've hit the wall between prototype and production — job management, agent isolation, long-running lifecycles. | -| **Raw LLM SDK calls** | You're tired of building the agent loop, checkpointing, and orchestration from scratch. | +| Getting started | [Getting Started](https://perstack.ai/docs/getting-started/) | +| Architecture and core concepts | [Understanding Perstack](https://perstack.ai/docs/understanding-perstack/concept/) | +| Expert definitions | [Making Experts](https://perstack.ai/docs/making-experts/) | +| Rapid prototyping | [Rapid Prototyping Guide](https://perstack.ai/guides/rapid-prototyping/) | +| Breaking agents into specialists | [Taming Prompt Sprawl](https://perstack.ai/guides/taming-prompt-sprawl/) | +| Adding tools via MCP | [Extending with Tools](https://perstack.ai/guides/extending-with-tools/) | +| Deployment | [Deployment](https://perstack.ai/docs/operating-experts/deployment/) | +| CLI and API reference | [References](https://perstack.ai/docs/references/cli/) | -Perstack is not a framework, an orchestrator, or a UI layer. It is an **agentic AI runtime** — the execution engine that sits between your application and the LLM providers. Define agents above it. Build interfaces on top of it. +## Status -Perstack is pre-1.0. The runtime is stable and used in production, but the API surface may evolve. [Pin your versions](https://perstack.ai/docs/references/cli/). +Pre-1.0. The runtime is stable and used in production, but the API surface may change. [Pin your versions](https://perstack.ai/docs/references/cli/). -## Join the Community +## Community -- **[Discord](https://discord.gg/perstack)** — Ask questions, share what you're building, get help. -- **[GitHub Issues](https://github.com/perstack-ai/perstack/issues)** — Bug reports, feature requests, ideas. -- **[@FL4T_LiN3 on X](https://x.com/FL4T_LiN3)** — Building Perstack in public. Follow for updates. +- [Discord](https://discord.gg/perstack) +- [GitHub Issues](https://github.com/perstack-ai/perstack/issues) +- [@FL4T_LiN3 on X](https://x.com/FL4T_LiN3) ## Contributing