Skip to content

docs: update walkthrough to match README and current state #733

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FL4TLiN3 merged 1 commit into from
Mar 8, 2026
Merged

docs: update walkthrough to match README and current state #733

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
140 changes: 31 additions & 109 deletions docs/getting-started/walkthrough.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -20,11 +20,11 @@ There are two ways to provide API keys:
Export the key on the host and forward it to the container:

```bash
export ANTHROPIC_API_KEY=sk-ant-...
export FIREWORKS_API_KEY=fw_...
docker run --rm -it \
-e ANTHROPIC_API_KEY \
-e FIREWORKS_API_KEY \
-v ./workspace:/workspace \
perstack/perstack start my-expert "query"
perstack/perstack start my-expert "query" --provider fireworks
```

**2. Store keys in a `.env` file in the workspace**
Expand All @@ -33,7 +33,7 @@ Create a `.env` file in the workspace directory. Perstack loads `.env` and `.env

```bash
# ./workspace/.env
ANTHROPIC_API_KEY=sk-ant-...
FIREWORKS_API_KEY=fw_...
```

```bash
Expand All @@ -53,20 +53,17 @@ perstack start my-expert "query" --env-path .env.production
Generate an Expert definition interactively:

```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 ANTHROPIC_API_KEY \
-e FIREWORKS_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."
--provider fireworks \
--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.
- 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
- iterates on definitions until behavior stabilizes
- reports capabilities and limitations
`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.

The result is a `perstack.toml` ready to use:

Expand Down Expand Up @@ -96,12 +93,14 @@ You can also write `perstack.toml` manually — `create-expert` is a convenient
### Interactive mode

```bash
# Let `ai-gaming` build a Wizardry-like dungeon crawler
docker run --pull always --rm -it \
-e ANTHROPIC_API_KEY \
-e FIREWORKS_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."
--provider fireworks \
--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."
```

`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.
Expand All @@ -110,11 +109,12 @@ docker run --pull always --rm -it \

```bash
docker run --pull always --rm \
-e ANTHROPIC_API_KEY \
-e FIREWORKS_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."
--provider fireworks \
--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."
```

`perstack run` outputs JSON events to stdout — designed for automation and CI pipelines.
Expand All @@ -133,7 +133,9 @@ docker run --pull always --rm \
After running an Expert, inspect what happened:

```bash
npx perstack log
docker run --rm -it \
-v ./ai-gaming:/workspace \
perstack/perstack log
```

By default, this shows a summary of the latest job — the Expert that ran, the steps it took, and any errors.
Expand All @@ -155,7 +157,9 @@ See [CLI Reference](../references/cli.md#perstack-log) for the full list of opti
## Lock for Reproducibility

```bash
npx perstack install
docker run --rm -it \
-v ./ai-gaming:/workspace \
perstack/perstack install
```

This creates a `perstack.lock` file that caches tool schemas for all MCP skills. Without the lockfile, Perstack initializes MCP skills at runtime to discover their tool definitions — which can add 500ms–6s startup latency per skill.
Expand All @@ -171,91 +175,9 @@ The lockfile is optional. If not present, skills are initialized at runtime as u

## Integrate into Your Application

The CLI is for prototyping. For production, integrate Experts into your application via the Execution API, sandbox providers, or runtime embedding.

### Perstack Execution API

The Execution API is the primary path for production integration. Your application starts jobs, streams events, and sends follow-up queries over HTTP.

#### REST API

**Start a job:**

```bash
curl -X POST https://api.perstack.ai/api/v1/jobs \
-H "Authorization: Bearer $PERSTACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"applicationId": "your-app-id",
"expertKey": "fitness-assistant",
"query": "Start today'\''s session",
"provider": "anthropic"
}'
```

**Stream events (SSE):**

```bash
curl -N https://api.perstack.ai/api/v1/jobs/{jobId}/stream \
-H "Authorization: Bearer $PERSTACK_API_KEY"
```

The stream emits Server-Sent Events: `message` events contain `PerstackEvent` payloads, `error` events signal failures, and `complete` events indicate the job finished.

**Continue a job:**

```bash
curl -X POST https://api.perstack.ai/api/v1/jobs/{jobId}/continue \
-H "Authorization: Bearer $PERSTACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"query": "Now create a weekly schedule"
}'
```

#### TypeScript SDK (`@perstack/api-client`)

```typescript
import { createApiClient } from "@perstack/api-client"

const client = createApiClient({
apiKey: process.env.PERSTACK_API_KEY,
})

// Start a job
const result = await client.jobs.start({
applicationId: "your-app-id",
expertKey: "fitness-assistant",
query: "Start today's session",
provider: "anthropic",
})

if (!result.ok) {
// result.error.type: "http" | "network" | "timeout" | "validation" | "abort"
console.error(result.error.message)
process.exit(1)
}

const jobId = result.data.data.job.id

// Stream events
const stream = await client.jobs.stream(jobId)

if (stream.ok) {
for await (const event of stream.data.events) {
console.log(event.type, event)
}
}

// Continue with a follow-up
await client.jobs.continue(jobId, {
query: "Now create a weekly schedule",
})
```

Every method returns an `ApiResult<T>` — either `{ ok: true, data }` or `{ ok: false, error }`. Error types are: `"http"`, `"network"`, `"timeout"`, `"validation"`, and `"abort"`.
The CLI is for prototyping. For production, integrate Experts into your application via sandbox providers or runtime embedding.

### Other Sandbox Providers
### Sandbox Providers

Perstack's isolation model maps naturally to container and serverless platforms:

Expand All @@ -276,8 +198,8 @@ import { run } from "@perstack/runtime"

const checkpoint = await run({
setting: {
providerConfig: { providerName: "anthropic" },
expertKey: "fitness-assistant",
providerConfig: { providerName: "fireworks" },
expertKey: "my-expert",
input: { text: "Start today's session" },
},
})
Expand All @@ -290,8 +212,8 @@ import { run } from "@perstack/runtime"

const checkpoint = await run({
setting: {
providerConfig: { providerName: "anthropic" },
expertKey: "fitness-assistant",
providerConfig: { providerName: "fireworks" },
expertKey: "my-expert",
input: { text: "Start today's session" },
},
eventListener: (event) => {
Expand Down