diff --git a/README.md b/README.md index b9a9b346..f8c5e8e2 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,50 @@ -# Perstack - -A harness for micro-agents. +# Perstack: A Harness for Micro-Agents.

License npm downloads npm version - Docker image version + Docker image version

- Documentation · + Docs · Getting Started · - Discord + Website · + Discord · + @FL4T_LiN3

-If you're looking for a way to build practical agentic apps like Claude Code or OpenClaw, you'll need a harness to manage the complexity. +If you want to build practical agentic apps like Claude Code or OpenClaw, a harness helps manage the complexity. Perstack is a harness for agentic apps. It aims to: -- **Do big things with small models**: If a smaller model can make the same thing, there's no reason to use a bigger model. -- **Quality is a system property, not a model property**: Building agentic software that people use doesn't require AI science degree, just knowledge to solve their problems. -- **Keep it simple and reliable**: The biggest mistake is cramming AI into an overly complex harness and ending up with an uncontrollable agent. +- **Do big things with small models**: If a smaller model can do the job, there's no reason to use a bigger one. +- **Quality is a system property, not a model property**: Building agentic software people actually use doesn't require an AI science degree—just a solid understanding of the problems you're solving. +- **Keep it simple and reliable**: The biggest mistake is cramming AI into an overly complex harness and ending up with an inoperable agent. ## Getting Started -Perstack is designed so that defining experts, running them, and integrating them into applications remain separate concerns. +Perstack keeps expert definition, orchestration, and application integration as separate concerns. `create-expert` scaffolds experts, the harness handles orchestration, and deployment stays simple because Perstack runs on standard container and serverless infrastructure. ### Defining your first expert -To get started, you can use the `create-expert` Expert that helps you to focus on the core and build your first agentic AI: +To get started, use the built-in `create-expert` expert to scaffold your first agentic app: ```bash -# Ask `create-expert` to form a team named `ai-gaming` +# Use `create-expert` to scaffold a micro-agent team named `ai-gaming` docker run --pull always --rm -it \ -e FIREWORKS_API_KEY \ -v ./ai-gaming:/workspace \ perstack/perstack start create-expert \ --provider fireworks \ - "Form a team named ai-gaming to build a Bun-based CLI cutting-edge indie game playable on Bash." + --model accounts/fireworks/models/kimi-k2p5 \ + "Form a team named ai-gaming to build a Bun-based CLI indie game playable on Bash for AI." ``` -`create-expert` is a built-in Expert. It 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. +`create-expert` is a built-in expert. It generates a `perstack.toml` that defines a team of micro-agents, runs them, evaluates the results, and iterates until the setup works. Each agent has a single responsibility and its own context window. Complex tasks are broken down and delegated to specialists. ```toml [experts."ai-gaming"] @@ -69,21 +70,37 @@ instruction = "Play-test the game, find bugs, and verify fixes." To let your agents work on an actual task, you can use the `perstack start` command to run them interactively: ```bash -# Let `ai-gaming` team build a Wizardry-like dungeon crawler +# Let `ai-gaming` build a Wizardry-like dungeon crawler docker run --pull always --rm -it \ -e FIREWORKS_API_KEY \ -v ./ai-gaming:/workspace \ perstack/perstack start ai-gaming \ --provider fireworks \ - "Make a Wizardry-like dungeon crawler. Make it replayable, so players can dive in, die, and find a way to beat it." + --model accounts/fireworks/models/kimi-k2p5 \ + "Create a Wizardry-like dungeon crawler in a fixed 10-floor labyrinth with complex layouts, traps, fixed room encounters, and random battles. Include special-effect gear drops, leveling, and a skill tree for one playable character. Balance difficulty around build optimization. Death in the dungeon causes loss of one random equipped item." ``` -Here is an example of a game built with these commands: [demo-dungeon-crawler](https://github.com/perstack-ai/demo-dungeon-crawler). It was built entirely using Kimi K2.5 on Fireworks for under $0.10 in total API cost. You can play it directly: +Here is an example of a game built with these commands: [demo-dungeon-crawler](https://github.com/FL4TLiN3/demo-dungeon-crawler). It was built entirely with Kimi K2.5 on Fireworks. You can play it directly: ```bash npx perstack-demo-dungeon-crawler start ``` +
+Generation stats for demo-dungeon-crawler + +| | | +|---|---| +| **Date** | March 8, 2026 | +| **Duration** | 32 min 44 sec | +| **Steps** | 199 | +| **Generated Code** | 13,587 lines across 25 files | +| **Tokens (Input)** | 11.4M (Cache: 10.7M) | +| **Tokens (Output)** | 257.3K | +| **Cost** | $2.27 (via Fireworks) | + +
+ ### Integrating with your app Perstack separates the agent harness from the application layer. Your app stays a normal web or terminal app, with no LLM dependencies in the client. @@ -91,8 +108,8 @@ Perstack separates the agent harness from the application layer. Your app stays ``` ┌─────────────────┐ ┌──────────────────┐ │ Your app │ events │ perstack run │ -│ (React, TUI…) │◄─────────── │ (@perstack/ │ -│ │ SSE / WS / │ runtime) │ +│ (React, TUI…) │ ◄─────────── │ (@perstack/ │ +│ │ SSE / WS / │ runtime) │ │ @perstack/ │ any stream │ │ │ react │ │ │ └─────────────────┘ └──────────────────┘ @@ -110,7 +127,7 @@ RUN perstack install ENTRYPOINT ["perstack", "run", "my-expert"] ``` -The image is ubuntu-based, multi-arch (`linux/amd64`, `linux/arm64`) and weighs ~74MB. The runtime can also be imported directly as a TypeScript library ([`@perstack/runtime`](https://www.npmjs.com/package/@perstack/runtime)) for serverless environments. See the [deployment guide](https://perstack.ai/docs/operating-experts/deployment/) for details. +The image is Ubuntu-based, multi-arch (`linux/amd64`, `linux/arm64`), and is ~74 MB. `perstack install` pre-resolves MCP servers and prewarms tool definitions for faster, reproducible startup. The runtime can also be imported directly as a TypeScript library ([`@perstack/runtime`](https://www.npmjs.com/package/@perstack/runtime)) for serverless environments. See the [deployment guide](https://perstack.ai/docs/operating-experts/deployment/) for details. ### Why micro-agents? @@ -166,27 +183,29 @@ perstack start my-expert "query" --env-path .env.production ## What's inside? -Perstack organizes the complexity of an agent harness into five layers with clear separation of concerns: +An agent harness needs a broad set of capabilities—almost like an operating system. ``` -┌──────────────────────────────────────────────────────────────────┐ -│ Interface │ -│ CLI · TUI · Event streaming · Programmatic API │ -├──────────────────────────────────────────────────────────────────┤ -│ Runtime │ -│ Agentic loop · Event-sourcing · Checkpointing · Tool use │ -├──────────────────────────────────────────────────────────────────┤ -│ Context │ -│ System prompts · Prompt caching · Agentic RAG · Extended thinking│ -├──────────────────────────────────────────────────────────────────┤ -│ Definition │ +┌──────────────────────────────────────────────────────────────────-┐ +│ Interface │ +│ CLI · Event streaming · Programmatic API │ +├──────────────────────────────────────────────────────────────────-┤ +│ Runtime │ +│ Agentic loop · Event-sourcing · Checkpointing · Tool use │ +├──────────────────────────────────────────────────────────────────-┤ +│ Context │ +│ System prompts · Prompt caching · AgenticRAG · Extended thinking │ +├──────────────────────────────────────────────────────────────────-┤ +│ Definition │ │ Multi-agent topology · MCP skills · Provider abstraction │ -├──────────────────────────────────────────────────────────────────┤ -│ Infrastructure │ +├──────────────────────────────────────────────────────────────────-┤ +│ Infrastructure │ │ Sandbox isolation · Workspace boundary · Secret management │ -└──────────────────────────────────────────────────────────────────┘ +└──────────────────────────────────────────────────────────────────-┘ ``` +Most of the features below are not new ideas. Perstack takes the usual harness building blocks — tool use, delegation, checkpointing, prompt caching, etc. — makes them easy to operate, puts them on top of standards you already know (MCP, TOML, Docker, SSE), and ships them as one runtime. Where cost or operational burden demands it, Perstack introduces its own take — micro-agents being the first example. +
Full feature matrix @@ -245,13 +264,12 @@ Perstack organizes the complexity of an agent harness into five layers with clea ## Status -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/). +Pre-1.0. The runtime is production-tested, but the API surface may change. [Pin your versions](https://perstack.ai/docs/references/cli/). ## Community - [Discord](https://discord.gg/2xZzrxC9) -- [GitHub Issues](https://github.com/perstack-ai/perstack/issues) -- [@FL4T_LiN3 on X](https://x.com/FL4T_LiN3) +- [Author on X(@FL4T_LiN3)](https://x.com/FL4T_LiN3) ## Contributing