From f2ff3f00411eee1f778be719c7d39799871bbf82 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Mon, 9 Mar 2026 07:57:17 +0900 Subject: [PATCH] docs: revamp docs/index.md for micro-agents focus - Update description and intro to reflect micro-agents positioning - Replace npx examples with Docker-based commands matching README - Add Fireworks provider and --model flag to Quick Start - Replace "Why Perstack?" with "Why Micro-Agents?" table - Add Operate section with Deployment and Isolation links - Add Providers and Models reference link - Remove broken /api/v1/spec link - Fix Discord and X community links Co-Authored-By: Claude Opus 4.6 --- docs/index.md | 59 ++++++++++++++++++++++++++++++++++----------------- 1 file changed, 39 insertions(+), 20 deletions(-) diff --git a/docs/index.md b/docs/index.md index 485525fa..ba709327 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,55 +1,74 @@ --- title: Perstack Documentation -description: Define AI agents as Experts in natural language. Execute them with deterministic, event-derived tracking. +description: A harness for micro-agents — build practical agentic apps that are cheaper and easier to operate. slug: docs pagefind: true --- -Define AI agents as **Experts** in natural language. Execute them with deterministic, event-derived tracking. Each Expert runs in its own isolated context — no shared state, no prompt bloat, full execution history. +Perstack is an open-source harness for micro-agents — purpose-specific agents with a single responsibility. + +Instead of one monolithic agent on a frontier model, you define a team of small, focused agents in TOML, and the runtime handles orchestration, isolation, and state. The result: agentic apps that are cheaper to run and easier to operate. ## Quick Start -Perstack is an open-source runtime for executing AI agents defined as Experts. Define behavior in TOML, run from the CLI or embed in your application. +Use the built-in `create-expert` expert to scaffold a micro-agent team, then run it: ```bash -# Generate an Expert using create-expert (a published Expert on the Perstack registry) -npx perstack start create-expert "Create a code-reviewer that delegates to a style-checker" - -# Run it -npx perstack start code-reviewer "Review PR #42 for security issues" +# Scaffold a micro-agent team +docker run --pull always --rm -it \ + -e FIREWORKS_API_KEY \ + -v ./my-project:/workspace \ + perstack/perstack start create-expert \ + --provider fireworks \ + --model accounts/fireworks/models/kimi-k2p5 \ + "Form a team to build a CLI app." + +# Run the generated expert +docker run --pull always --rm -it \ + -e FIREWORKS_API_KEY \ + -v ./my-project:/workspace \ + perstack/perstack start my-expert \ + --provider fireworks \ + --model accounts/fireworks/models/kimi-k2p5 \ + "Build me a CLI todo app with priorities and due dates." ``` -## Why Perstack? +See [Getting Started](/docs/getting-started/walkthrough/) for a full walkthrough. -Agent frameworks help you **build** agents. Perstack is a **runtime** that **executes** them. You define Experts in natural language via TOML — Perstack handles execution, isolation, and state. +## Why Micro-Agents? | | | | :--- | :--- | -| **Natural-language definitions** | Expert definitions in `perstack.toml` are plain text. Domain experts write the behavior; developers focus on integration. | -| **Isolation by design** | Each Expert runs in its own context — workspace boundaries, environment sandboxing, and tool whitelisting. No shared state between runs. | -| **Event-derived execution** | Step-level checkpoints make runs reproducible. Resume from any step, debug, replay, and audit every decision. | -| **Multi-provider support** | Anthropic, OpenAI, Google, DeepSeek, Ollama, Azure, Bedrock, Vertex. Switch providers with one config change. | +| **Cost-effective** | Purpose-specific agents run on affordable models. A focused agent on a cheap model outperforms a generalist on an expensive one. | +| **Fast** | Smaller models generate faster. Fine-grained tasks run concurrently via parallel delegation. | +| **Reusable** | Delegates are dependency management for agents — like npm packages or crates. Compose purpose-built experts across projects. | +| **Maintainable** | Single-responsibility experts are independently testable. Test each one, then compose them. | ## Explore the Docs ### Learn -- [**Getting Started**](/docs/getting-started/walkthrough/) — create your first Expert and walk through the core workflow -- [**Concepts**](/docs/understanding-perstack/concept/) — understand the architecture behind Experts, runtime, isolation, and the boundary model +- [**Getting Started**](/docs/getting-started/walkthrough/) — create your first expert and walk through the core workflow +- [**Concepts**](/docs/understanding-perstack/concept/) — understand the architecture behind experts, runtime, isolation, and the boundary model ### Build -- [**Making Experts**](/docs/making-experts/best-practices/) — complete guide to defining Experts with skills, delegation, testing, and best practices +- [**Making Experts**](/docs/making-experts/best-practices/) — defining experts with skills, delegation, testing, and best practices - [**Guides**](/docs/guides/rapid-prototyping/) — task-oriented walkthroughs from rapid prototyping to production deployment +### Operate + +- [**Deployment**](/docs/operating-experts/deployment/) — container images, serverless integration, and `perstack install` +- [**Isolation & Security**](/docs/operating-experts/isolation-by-design/) — sandbox design, workspace boundaries, and secret management + ### Reference - [**CLI Reference**](/docs/references/cli/) — all commands and options for the Perstack CLI - [**perstack.toml Reference**](/docs/references/perstack-toml/) — complete configuration specification -- [**API Reference**](/api/v1/spec) — REST API documentation for the Execution API +- [**Providers and Models**](/docs/references/providers-and-models/) — supported providers and model configuration ## Community - [GitHub](https://github.com/perstack-ai/perstack) — source code and issues -- [Discord](https://discord.gg/perstack) — chat with the community -- [X (@perstack_ai)](https://x.com/perstack_ai) — updates and announcements +- [Discord](https://discord.gg/2xZzrxC9) — chat with the community +- [@FL4T_LiN3 on X](https://x.com/FL4T_LiN3) — updates and announcements