diff --git a/docs/getting-started/walkthrough.mdx b/docs/getting-started/walkthrough.mdx index eaa1ed0e..180fa971 100644 --- a/docs/getting-started/walkthrough.mdx +++ b/docs/getting-started/walkthrough.mdx @@ -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** @@ -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 @@ -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: @@ -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. @@ -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. @@ -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. @@ -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. @@ -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` — 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: @@ -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" }, }, }) @@ -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) => {