From 33b2056bf31aa0fa660045dcf7192a5fe43fd557 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sun, 1 Mar 2026 12:11:58 +0900 Subject: [PATCH] docs: update README stack model and migrate walkthrough/concept to mdx MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Update README how-it-works section (inference budgets → memory, env vars formatting) - Migrate walkthrough.md → walkthrough.mdx - Migrate concept.md → concept.mdx Co-Authored-By: Claude Opus 4.6 --- README.md | 4 +- .../{walkthrough.md => walkthrough.mdx} | 97 ++++++++++++++----- docs/understanding-perstack/concept.md | 97 ------------------- docs/understanding-perstack/concept.mdx | 50 ++++++++++ 4 files changed, 126 insertions(+), 122 deletions(-) rename docs/getting-started/{walkthrough.md => walkthrough.mdx} (69%) delete mode 100644 docs/understanding-perstack/concept.md create mode 100644 docs/understanding-perstack/concept.mdx diff --git a/README.md b/README.md index 133a76f3..d7c80edc 100644 --- a/README.md +++ b/README.md @@ -116,9 +116,9 @@ perstack start my-expert "query" --env-path .env.production Perstack organizes the complexity of micro-agents harness design into a simple stack model: - **Definition**: `perstack.toml`, Experts, skills, providers -- **Context**: Context windows, workspace, delegations, inference budgets +- **Context**: Context windows, workspace, delegations, memory - **Runtime**: Event-sourcing, checkpoints, skill management -- **Infrastructure**: Container isolation, workspace boundaries, env vars, secrets +- **Infrastructure**: Container isolation, workspace boundaries, env vars/secrets - **Interface**: `perstack` CLI, JSON-event via `@perstack/runtime` For details, see [Understanding Perstack](https://perstack.ai/docs/understanding-perstack/concept/). diff --git a/docs/getting-started/walkthrough.md b/docs/getting-started/walkthrough.mdx similarity index 69% rename from docs/getting-started/walkthrough.md rename to docs/getting-started/walkthrough.mdx index 0e01dd88..e11f558c 100644 --- a/docs/getting-started/walkthrough.md +++ b/docs/getting-started/walkthrough.mdx @@ -8,11 +8,44 @@ This walkthrough takes you from zero to production integration. ## Prerequisites -- [Node.js 22+](https://nodejs.org/) +- Docker - An LLM provider API key (see [Providers and Models](../references/providers-and-models.md)) +### Giving API keys + +There are two ways to provide API keys: + +**1. Pass host environment variables with `-e`** + +Export the key on the host and forward it to the container: + ```bash export ANTHROPIC_API_KEY=sk-ant-... +docker run --rm -it \ + -e ANTHROPIC_API_KEY \ + -v ./workspace:/workspace \ + perstack/perstack start my-expert "query" +``` + +**2. Store keys in a `.env` file in the workspace** + +Create a `.env` file in the workspace directory. Perstack loads `.env` and `.env.local` by default: + +```bash +# ./workspace/.env +ANTHROPIC_API_KEY=sk-ant-... +``` + +```bash +docker run --rm -it \ + -v ./workspace:/workspace \ + perstack/perstack start my-expert "query" +``` + +You can also specify custom `.env` file paths with `--env-path`: + +```bash +perstack start my-expert "query" --env-path .env.production ``` ## Create an Expert @@ -20,10 +53,15 @@ export ANTHROPIC_API_KEY=sk-ant-... Generate an Expert definition interactively: ```bash -npx perstack start create-expert "Create a fitness assistant that delegates to a pro trainer" +# Ask `create-expert` to form a team named `ai-gaming` +docker run --pull always --rm -it \ + -e ANTHROPIC_API_KEY \ + -v ./ai-gaming:/workspace \ + perstack/perstack start create-expert \ + "Form a team named ai-gaming to build a Bun-based CLI cutting-edge indie game playable on Bash." ``` -`create-expert` is a published Expert on the [Perstack registry](https://perstack.ai/) — no local config file is needed. The CLI resolves it from the registry automatically. It does more than scaffold a file — it: +`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. - generates Expert definitions in `perstack.toml` based on your description - tests them against real-world scenarios - analyzes execution history and output to evaluate the definitions @@ -33,29 +71,37 @@ npx perstack start create-expert "Create a fitness assistant that delegates to a The result is a `perstack.toml` ready to use: ```toml -# perstack.toml - -[experts."fitness-assistant"] -description = "Manages fitness records and suggests training menus" -instruction = """ -Conduct interview sessions and manage records in `./fitness-log.md`. -Collaborate with `pro-trainer` for professional training menus. -""" -delegates = ["pro-trainer"] - -[experts."pro-trainer"] -description = "Suggests scientifically-backed training menus" -instruction = "Provide split routines and HIIT plans tailored to user history." +[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"] + +[experts."@ai-gaming/level-designer"] +description = "Designs dungeon layouts and game mechanics" +instruction = "Design engaging dungeon levels, enemy encounters, and progression systems." + +[experts."@ai-gaming/programmer"] +description = "Implements the game in TypeScript" +instruction = "Write the game code using Bun, targeting terminal-based gameplay." + +[experts."@ai-gaming/tester"] +description = "Tests the game and reports bugs" +instruction = "Play-test the game, find bugs, and verify fixes." ``` -You can also write `perstack.toml` manually — `perstack start create-expert` is a convenient starting point, not a requirement. +You can also write `perstack.toml` manually — `create-expert` is a convenient assistant, not necessary. ## Run Your Expert ### Interactive mode ```bash -npx perstack start fitness-assistant "Start today's session" +docker run --pull always --rm -it \ + -e ANTHROPIC_API_KEY \ + -v ./ai-gaming:/workspace \ + perstack/perstack start ai-gaming \ + --model "haiku-4-5" \ + "Make a Wizardry-like dungeon crawler. Make it replayable, so players can dive in, die, and find a way to beat it." ``` `perstack start` opens a text-based UI for developing and testing Experts. You get real-time feedback and can iterate on definitions without deploying anything. @@ -63,7 +109,12 @@ npx perstack start fitness-assistant "Start today's session" ### Headless mode ```bash -npx perstack run fitness-assistant "Start today's session" +docker run --pull always --rm \ + -e ANTHROPIC_API_KEY \ + -v ./ai-gaming:/workspace \ + perstack/perstack run ai-gaming \ + --model "haiku-4-5" \ + "Make a Wizardry-like dungeon crawler. Make it replayable, so players can dive in, die, and find a way to beat it." ``` `perstack run` outputs JSON events to stdout — designed for automation and CI pipelines. @@ -72,10 +123,10 @@ npx perstack run fitness-assistant "Start today's session" | Aspect | What Perstack Does | | --- | --- | -| **State** | Both Experts share the workspace (`./fitness-log.md`), not conversation history. | -| **Collaboration** | `fitness-assistant` delegates to `pro-trainer` autonomously. | -| **Observability** | Every step is visible as a structured event. | -| **Isolation** | Each Expert has its own context window. No prompt bloat. | +| **State** | All Experts share the workspace (`./workspace`), not conversation history. | +| **Collaboration** | Coordinator(`ai-gaming`) delegates to Delegated Experts(`@ai-gaming/level-designer`, `@ai-gaming/programmer`, `@ai-gaming/tester`) autonomously. | +| **Observability** | Every step is visible as a structured JSON event. | +| **Isolation** | Job is executed in sandboxed environment safely. Each Expert has its own context window. | ## Analyze Execution diff --git a/docs/understanding-perstack/concept.md b/docs/understanding-perstack/concept.md deleted file mode 100644 index 4e3eecf8..00000000 --- a/docs/understanding-perstack/concept.md +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "Concept" -sidebar: - order: 1 ---- - -Perstack is built on a concept called **Expert Stack** — the architecture that enables agent-first development. - -> [!NOTE] -> The name "Perstack" combines the Latin word "perītus" (meaning "expert") with "stack". Perstack = Expert Stack. - -## Vision - -The future of software is agentic. Cursor transformed coding. The same shift is coming to CRM, e-commerce, support — every domain where software helps users achieve goals. - -But today, building agentic apps means building monoliths. Context explodes, agents can't collaborate, and only the original author can maintain the system. Frameworks help you build, but nothing helps you reuse. - -**Perstack exists to change this.** We're building the toolkit so any developer can compose high-quality agentic experiences from proven, reusable components — without starting from zero. - -This requires a different approach to development. - -## What is agent-first? - -Agent-first means focusing on **what the agent should be**, not on how to build applications or runtimes around it. - -- **Definition-focused**: You define the agent's role, knowledge, and capabilities — nothing more -- **Right people define**: The people who know "what it should be" (domain experts) write the definitions -- **Runtime realizes**: The system interprets definitions and makes them work — you don't implement the mechanics - -This is the opposite of runtime-first (building orchestration logic) or application-first (embedding agents in app code). Agent-first development separates **what** from **how** — you focus on the essential knowledge, the runtime handles orchestration, state, and safety. - -## Expert Stack vs. Agent Frameworks - -Perstack isn't an agent framework. It solves a different problem. - -Agent frameworks focus on **how to build** agent applications — orchestration, tool calling, memory management. The artifact is an application tied to that framework. - -Expert Stack focuses on **how to define, share, and reuse** agent capabilities. The artifact is a portable Expert definition that any system can consume. - -| | Agent Framework | Expert Stack | -| ------------------- | ---------------------------- | -------------------------------------------- | -| **Developer's job** | Implement behavior in code | Define roles declaratively | -| **Format** | Code (Python, TypeScript) | Plain text (TOML) | -| **Execution** | Your code runs | Runtime interprets definitions | -| **Artifact** | Framework-dependent app | Portable Expert definition | -| **Reuse** | Copy code or wrap as library | Publish to registry, reference as dependency | - -Most agent frameworks optimize for building applications, not for reusing what's built. Expert Stack was designed from the ground up with reusability as a first-class concern. - -Expert definitions are plain text with no framework dependency. Any agent framework can consume them through the [API](https://perstack.ai/api/v1/spec). The ecosystem is open. - -## The three goals - -These features work together to achieve three goals. When all three are met, agent-first development becomes practical — efficient, easy to operate, and safe. - -### Isolation - -Isolation means separating an agent from everything except its role — that's what makes it a true Expert. - -- **Model isolation**: the runtime mediates access to LLMs -- **Role isolation**: each Expert focuses on one job -- **Control isolation**: all controls live in tools; Experts only decide how to use them -- **Dependency isolation**: collaboration is resolved by the runtime -- **Context isolation**: context windows are never shared; data flows through runtime/workspace -- **Sandbox support**: designed to align with infra-level isolation - -**Why context isolation matters for security:** - -Each Expert has different skills with different capabilities. Some skills access secrets (API keys, credentials). Some skills retrieve sensitive data (customer records, internal documents). This means an Expert's context may contain information with attack value. - -If contexts were shared between Experts, a malicious or compromised Expert could extract secrets and sensitive data from another Expert's context. Context isolation prevents this by design — each Expert sees only its own instruction and the query it receives. No message history, no parent context, no leaked secrets. - -This isn't just about preventing prompt bloat. It's a security boundary. - -### Observability - -Observability means agent behavior is fully transparent and inspectable. - -- **Prompt visibility**: no hidden instructions or context injection -- **Definition visibility**: only `perstack.toml` or registry definitions execute -- **Registry visibility**: write-once per version; text-only, fully auditable -- **Tool visibility**: tools run through MCP; usage is explicit -- **Internal state visibility**: state machines emit visible events -- **Deterministic history**: checkpoints make runs reproducible - -This isn't just for debugging. Observability is a [prerequisite for sandbox integration](./sandbox-integration.md#observability-as-a-prerequisite) — you verify behavior after the fact, not before. - -### Reusability - -Reusability enables agents to collaborate as components — the path to more capable agentic apps. - -An Expert is a modular micro-agent: -- Built for a specific purpose -- Reliable at one thing -- Modular and composable - -An agent represents a user. An Expert is a specialist component that helps an application achieve its goals. diff --git a/docs/understanding-perstack/concept.mdx b/docs/understanding-perstack/concept.mdx new file mode 100644 index 00000000..47cc8895 --- /dev/null +++ b/docs/understanding-perstack/concept.mdx @@ -0,0 +1,50 @@ +--- +title: "Concept" +sidebar: + order: 1 +--- + +import { LinkCard, CardGrid } from '@astrojs/starlight/components'; + +Perstack is built on a concept called **Expert Stack** — the harness that enables agentic AI to be more reliable and practically useful. + +> [!NOTE] +> The name "Perstack" combines the Latin word "perītus" (meaning "expert") with "stack". Perstack = Expert Stack. + +## Expert Stack + +Perstack organizes the complexity of micro-agents harness design into a simple stack model: + +### Definition + + + Purpose-specific micro-agents. + MCP tools (file ops, exec, custom MCP servers). + LLM providers and models. + Declarative definition of experts, skills, and providers. + + +### Context + + + The context in which experts operate. + The shared workspace in which experts operate. + The delegation of tasks to other experts. + The memory of the expert stack. + + +### Runtime + + + The event-sourcing of the expert stack. + The checkpoints of the expert stack. + The skill management of the expert stack. + + +### Infrastructure + + + The container isolation of the expert stack. + The workspace boundaries of the expert stack. + The env vars/secrets of the expert stack. +