Start with one useful agent. Add tools, sessions, retrieval, orchestration, serving, and production controls without changing frameworks.
import { agent, tool } from 'confused-ai';
import { z } from 'zod/v3';
const getQuote = tool({
name: 'get_quote',
description: 'Return a stock quote for a ticker symbol.',
parameters: z.object({ symbol: z.string() }),
execute: async ({ symbol }) => ({ symbol, price: 927.5, changePct: 1.4 }),
});
const financeAgent = agent({
name: 'finance-agent',
model: 'gpt-4o-mini',
instructions: 'Use the tool to answer market questions in one sentence.',
tools: [getQuote],
});
const result = await financeAgent.run("What's NVDA trading at today?");
console.log(result.text);Single install
One package, clear public subpaths, no consumer-facing monorepo imports
Layered growth
Start small and add runtime features in the order real systems need them
Runtime ready
Serve, schedule, observe, and harden agents without leaving the framework
Coordination built in
Move from one agent to workflows, supervisors, and teams when the task demands it
Build in layers
The cleanest path is to prove one agent first, then add only the missing layer: tools for live access, sessions for continuity, retrieval for grounded answers, serving for delivery, orchestration for coordination, and production controls for safe operation.
What the package gives you
Three primitives
The smallest useful unit. Use it when one model-backed worker can solve the task with clear instructions and explicit capabilities.
Use teams when the work benefits from specialists, routing, delegation, handoffs, or explicit supervisory control.
Use workflows when the sequence, branching, or structure of execution matters as much as the text the model returns.
Start here
Learn the product story, the layered mental model, and the recommended adoption order.
Build the first successful run without pulling in advanced layers too early.
Use runnable examples when you want concrete patterns for tools, retrieval, orchestration, and production hardening.
Read the docs in this order if you are new to the framework:
guide/introduction for the mental model.guide/getting-started for the first implementation path.examples/ for runnable patterns.api/ when you want a compact map of the public surfaces.| Capability | What it gives you |
|---|---|
| Agents | model, instructions, tools, and runtime behavior in one unit |
| Teams and workflows | specialists, supervisors, routing, and structured execution |
| Tools | explicit system boundaries for live data and side effects |
| Sessions and memory | continuity and retained facts |
| Knowledge and storage | source-backed answers and durable state |
| Serve and schedule | HTTP delivery and timed execution |
| Observe and evaluate | traces, metrics, and regression checks |
| Guard and approve | validation, policies, and human checkpoints |
All public docs should describe the framework as one package: confused-ai, plus focused public subpaths when a capability has its own runtime surface. Internal workspace packages are not the consumer-facing API story.