pocket-agent

Plan-driven agent orchestration for Node. You plug in a planner, executor, and evaluator (e.g. backed by any LLM); the framework runs the loop-plan → steps → evaluate → retry or replan-so you don’t re-implement it.

Author: sam_thewise

In a nutshell

• Goal in → plan → steps → evaluate → done. You give a goal; we get a machine-readable plan, run steps in dependency order, evaluate completion, and retry or replan as needed.
• You bring: planner, executor, evaluator (and optional tools). We bring: scheduling, lifecycle events, retries, and structured outputs.
• Pocket = small, drop-in. Agent = orchestration that turns your LLM into a plan-first workflow.

What this does (plain terms)

You give a goal (e.g. “Summarize this contract” or “How does this codebase work?”). The library turns that into a plan: a ordered list of steps, each with a clear objective and inputs/outputs. It runs the steps one by one (or in order when steps depend on each other), uses your model (LLM) and optional tools to do the work, then asks an evaluator whether each step is actually done. If not, it retries or replans; when everything’s done, you get a single result with all the step outputs. You don’t wire the loop yourself-you plug in how to plan, how to run a step, and how to judge completion; the runner does the rest.

Terms you’ll see:

| Term | Meaning | |------|--------| | Runner | The thing you create with createAgentRunner or createQuickAgent. It runs the full loop: create plan → run steps → evaluate → retry/replan → return result. | | Plan | A list of steps (each has an id, objective, inputs, outputs, dependencies). The runner executes steps in an order that respects dependencies. | | Planner | Your code (or a built-in) that, given a goal and context, produces a plan. “What steps do we need to achieve this goal?” | | Executor | Your code (or a built-in) that runs one step. It gets the step definition, resolved inputs, and optional model and tools; it returns the step’s output (or error). “Do this step.” | | Evaluator | Your code (or a built-in LLM evaluator) that, given a step and its attempt result, says whether the step is complete, should retry, replan, or failed. “Is this step actually done?” | | Tools | Optional functions the executor can call during a step (e.g. read a file, call an API). The plan says which steps are allowed to use which tools. | | Model | The LLM (OpenAI, Anthropic, Gemini, Ollama, etc.) used by the executor (and often the evaluator). You pass it via a provider + API key or a custom adapter. | | Provider | Shortcut name for a model backend: "openai", "anthropic", "gemini", "ollama", "lmstudio". Setting provider lets the library create the model adapter and a default evaluator from env. |

Once these mean something, the rest of the doc (quick start, fluent plan, default evaluators, contracts) should fall into place.

Features

• Explicit plans - Machine-readable step list before execution
• Dependency-ordered execution - Steps run when their dependencies are satisfied
• Lifecycle events - run.started, plan.created, step.started, step.completed, run.completed, etc.
• Bounded retries - Evaluator-driven completion with configurable retry policy
• Structured outputs - Per-step and final run outputs

Install

npm install pocket-agent

Examples (quick start)

1. Super quick start (one call)

Set your API key in the environment, then create and run in two lines. Uses a single-step plan and the LLM to answer; no planner or executor code to write.

import { createQuickAgent } from "pocket-agent";

const runner = createQuickAgent({ provider: "openai" });
const run = await runner.run({ goal: "What is 2+2? Explain in one sentence." });

console.log(run.outputs?.answer);

Supported provider: "openai" | "anthropic" | "gemini" | "ollama" | "lmstudio". Each reads from env (e.g. OPENAI_API_KEY, OPENAI_MODEL). Optional modelConfig and systemPrompt. No tools in this mode; for tools and multi-step plans, see the docs below.

2. Goal-only with LLM-generated steps

Give a goal and let the LLM invent the plan (the list of steps). Use createGoalDrivenAgent with useLLMPlanner: true:

import { createGoalDrivenAgent } from "pocket-agent";

const runner = createGoalDrivenAgent({
  provider: "openai",
  useLLMPlanner: true,
  llmPlannerOptions: { maxSteps: 5, planHint: "Use 2–4 clear steps." },
});

const run = await runner.run({
  goal: "Explain what an API is in three short steps: definition, why it matters, one example.",
});

console.log(run.plan.steps);  // steps were generated by the LLM
console.log(run.outputs);

3. Custom planner and executor

When you want your own plan or execution logic, use createAgentRunner with a planner, executor, and evaluator (or provider for a default evaluator):

import { createAgentRunner } from "pocket-agent";

const runner = createAgentRunner({
  provider: "openai",
  planner,   // your Planner or use createFixedPlanPlanner(steps)
  executor,  // your StepExecutor or use createDefaultExecutor({ model })
  tools: {}, // optional
});

const run = await runner.run({
  goal: "Find the latest contract, extract payment terms, and summarize risks.",
  context: { customerId: "abc123" },
});

For fluent step definitions and a minimal planner/executor/evaluator, see the docs below.

Using from AI coding agents (Cursor, Claude, etc.)

You can treat pocket-agent like any other npm package when you’re coding inside tools like Cursor or Claude.

1. Install

npm install pocket-agent

Optionally add a provider SDK (e.g. OpenAI):

npm install openai

Set your env vars (for example, OpenAI):

• OPENAI_API_KEY – your key
• OPENAI_MODEL (optional) – defaults are documented in the docs

2. Quick one-function usage

Use the built-in quick agent when you just want “goal in → answer out”:

import { createQuickAgent } from "pocket-agent";

const runner = createQuickAgent({ provider: "openai" });

export async function runPocketAgent(goal: string) {
  const run = await runner.run({ goal });
  return run.outputs?.answer ?? run.outputs;
}

Now anywhere in your code (or from an AI coding agent), you can call:

const result = await runPocketAgent("Summarize the architecture of this repo.");
console.log(result);

For a longer guide, see Using pocket-agent from AI coding agents.

Documentation

More guides:

| Doc | Description | |-----|-------------| | Fluent plan and defaults | Build plans with step() + createFixedPlanPlanner and run with createDefaultExecutor. | | Custom planner and executor | Minimal planner, executor, and evaluator (full code). | | Default evaluators and providers | Provider table, provider in createAgentRunner, adapters. | | Contracts | Planner, StepExecutor, StepEvaluator, Tools. | | Events | Event-driven usage with runner.start(). | | API key and local models | Cloud (OpenAI), Ollama, LM Studio, tools, project planner. | | Using with AI agents | How to use pocket-agent from Cursor, Claude, and other AI coding tools. | | Examples | All runnable scripts (npm run example:*). |

Scripts

• npm run build - compile TypeScript to dist/
• npm test - run tests
• npm run test:watch - run tests in watch mode
• npm run example:quick-start - quick-start example
• npm run example:fluent-plan - fluent plan example
• npm run example:goal-driven-llm - goal-only with LLM-generated steps
• npm run example:minimal - minimal planner/executor/evaluator (no API key)
• npm run example:openai - full run with tools (OpenAI or local)
• npm run example:planner - project structure from a description

See Examples for the full list and what each script does.