Examples

The fastest way to learn the platform is to scaffold a working project and read it. The create-agents scaffolder ships two complete templates that exercise agents, connectors, skills, actions, and human-in-the-loop review.

#Overview

Each template is a single typed TypeScript package where the file name is the primitive’s identity — no registries, no manual wiring. Two templates are available:

starter — a minimal research-and-review project: a researcher, a summarizer that delegates to it, a reviewer with typed actions, a filesystem connector, one skill, and example client code.
market-intel (default) — a multi-agent arbitrage workflow: an orchestrator that delegates per-market pricing, parallel marketplace scouting, and bid strategy to specialist sub-agents, then submits a human-approval-gated listing proposal.

$ pnpm create @kraken-ai/agents my-project --template starternpm create @kraken-ai/agents my-project --template starter

$ pnpm create @kraken-ai/agents my-project --template market-intelnpm create @kraken-ai/agents my-project --template market-intel

For the scaffolder’s full flag set, see the CLI reference.

#Starter template

The starter project demonstrates the core building blocks in isolation: a connector that perceives and acts, a skill that carries procedure, typed actions for structured output, a team that delegates, and client code that calls agents from your own application.

my-project/ package.json tsconfig.json .env.example README.md src/ agents/ researcher.tsReads files via the filesystem connector summarizer.tsOrchestrates the researcher as a team member reviewer.tsApproves or rejects content via actions connectors/ filesystem.tsTools: fs_read, fs_write, fs_list skills/ research-guidelines/ SKILL.mdSkill frontmatter + procedure body actions/ approve.tsTyped outbound action reject.tsTyped outbound action clients/ chat.tsStream a chat with an agent action-client.tsRun an agent with typed action handlers

researcher → summarizer team — researcher.ts reads and analyzes files; summarizer.ts declares researcher as a team member and delegates file work to it, then synthesizes the findings.
Filesystem connector — filesystem.ts exposes fs_read, fs_write, and fs_list tools scoped to a data directory, with path-traversal protection.
Skill — research-guidelines/SKILL.md is a versioned procedure the researcher loads on demand to follow a consistent methodology.
Actions — approve.ts and reject.ts are typed structured outputs the reviewer emits; each has a Zod schema and a handler.
Clients — chat.ts streams a conversation with an agent; action-client.ts registers typed action handlers and runs the reviewer, both via PlatformClient.

How to run it:

$ cd my-project
$ cp .env.example .env   # fill in your model provider key
$ pnpm dev               # picks researcher / summarizer / reviewer

# Try the client examples
$ npx tsx src/clients/chat.ts
$ npx tsx src/clients/action-client.ts

#Market intelligence template

The market-intelligence project is a pallet-liquidation workflow. A pure orchestrator with no direct tools follows a skill as a runbook: it prices a device pallet per market, scouts three marketplaces in parallel, picks the best market, sets a bid strategy, then submits a listing proposal that pauses for human approval.

liquidator — the orchestrator. No direct tools; it only delegates to teammates and follows the urgent-liquidation-playbook skill. Carries a cron trigger so it runs hourly, and can also be run manually.
pricing-analyst — looks up fair-market value per market and cosmetic grade through the Orakle connector and returns mix-weighted per-market averages.
marketplace-scout — analyzes a single private-auction marketplace; the orchestrator delegates to three instances in parallel, one per city.
bid-strategist — picks a starting-bid discount and a confidence score for clearing the pallet within the target window.

Team delegation and human approval. liquidator declares the three specialists as team members and issues parallel scout delegations in a single turn. Its final step calls the submit-deal action, which is gated by a governance policy: the run pauses, a reviewer receives an approval card, and the action handler runs only on approval. See Human-in-the-Loop and Governance & Policies.

my-project/ package.json tsconfig.json .gitignore .env.example README.md src/ agents/ liquidator.tsPure orchestrator (delegation only) pricing-analyst.tsOrakle FMV per (market x grade) marketplace-scout.tsAnalyzes one auction; run x3 in parallel bid-strategist.tsStarting-bid % + confidence actions/ submit-deal.tsHuman-approval-gated listing action skills/ urgent-liquidation-playbook/ SKILL.mdStep-by-step runbook for the orchestrator connectors/ orakle.tsFair-market-value pricing connector london-private-auction.tsLondon marketplace demand nyc-private-auction.tsNYC marketplace demand dubai-private-auction.tsDubai marketplace demand

Note

The Orakle connector falls back to per-market mock data when no provider key is set, so the workflow runs end to end out of the box. Set ORAKLE_API_KEY in .env to use live pricing.

#Running an example

Scaffold the project

Pick a template and let the scaffolder generate, install, and initialize a git repository.
```
$ npx @kraken-ai/create-agents my-project --template starter
```
Set your model key

Copy the generated .env.example to .env and fill in the provider key for the model you scaffolded with — a google/* model expects GOOGLE_API_KEY, an openai/* model expects OPENAI_API_KEY.
```
$ cd my-project
$ cp .env.example .env
```
Run an agent locally

kraken dev runs an agent on your machine — no deployed platform required. With more than one agent it prompts you to choose.
```
$ pnpm dev
```
For deploying the project and the full CLI surface, see the CLI reference and Deployment.

#Next steps

Quickstart — Go from an empty directory to a running agent, then deploy by connecting a repository.
Agents — Define single agents and multi-agent teams, configure models, and wire in connectors, skills, and actions.
CLI — Every command and flag for the kraken CLI and the create-agents scaffolder.