Home - agbossjs/agboss GitHub Wiki

AGBoss

CI coverage

Typed agent workflows on LangGraph, in TypeScript. Agents, tools, MCP servers and knowledge bases are Angular-style components โ€” annotated classes, wired by a @Workflow module, dependencies through the constructor, every link checked by the compiler. Routing and judging by decision models (Jev, โ€ฆ), FinOps on every call, Terns and evaluation, profiles and comparisons, tracing.

The repository holds two things:

  1. The framework โ€” the npm package agboss (packages/agboss), its CLI agboss (packages/agboss-cli), the in-repo example examples/flow-patterns, and the eight standalone reference applications in agbossjs/agboss-examples (01-hello-agboss through 08-job-scout, #489).
  2. The delivery conveyor โ€” how the code is built with Claude Code: tickets move Triage โ†’ Backlog โ†’ In progress โ†’ Test โ†’ Done on the repo's board. See Delivery Pipeline.

Every ```ts block of this wiki compiles against the current package: CI clones the wiki and runs node scripts/check-docs.mjs --wiki wiki (the same check as the repo's docs). The project skills the package ships (packages/agboss/skills/**, #305) are checked the same way by npm run check:docs, plus: SKILL.md's version header is the package's version, every [x.y] code they mention exists, the names of their matrix (packages/agboss/tests/skills/coverage.ts) are in their files and exported by a public entry, and โ€” once reference 11 declares its catalog complete โ€” it lists every RuleCode.

Quick start

npx -p agboss-cli agboss create my-agents   # questionnaire โ†’ a working project (see [CLI](CLI))
cd my-agents && cp .env.example .env && npx agboss chat

Or add it to a project: npm i agboss and npm i -D agboss-cli, then write the components (Components).

The project is ready for coding agents (#305): AGENTS.md (Cursor, Codex, โ€ฆ) and a one-line CLAUDE.md (@AGENTS.md, for Claude Code) route each task to the framework's skills in .claude/skills/agboss/, which agboss check keeps equal to the installed agboss. Put the project's own rules under ## Project rules in AGENTS.md โ€” never in the skills folder, which is replaced on every upgrade (CLI โ†’ Project skills).

Agent Core

flowchart LR
  T([message]) --> B{daily limit left?}
  B -- no --> X([LimitExceededError, no calls])
  B -- yes --> E[workflow start]
  E --> R{router ยท Jev<br/>input guardrails}
  R -- profiler / scout / โ€ฆ --> A[agent ยท Kimi<br/>input + output guardrails]
  A --> C[workflow finish]
  C --> O([answer + path + cost report])
Loading

The workflow file is the graph: paths through a workflow start, routers, agents, actions and workflow finishes, each step's result written on the edge (Workflow). A message enters at the workflow start; a router chooses one of its routes, an agent reads its typed input from the path and answers, and the path goes on to a workflow finish โ€” loops are explicit and bounded by maxVisits. Limits (steps, visits, spend per run and per day) fail the run instead of letting it loop, unless the path's .onError(โ€ฆ) takes the failure. The result (ExecutionOutput) is the finish's output, the path taken and an itemised cost report.

What makes it a framework, not an example

Property How
Components Agents, tools and MCP servers are annotated classes in folders; a @Workflow module wires them by class reference (Components)
Routing by a decision model Routers default to Jev (TypeSafe) via the OpenRouter Decisions API: calibrated probabilities over the options and exact cost per call, instead of parsing free text. Any @Router can name a chat model instead โ†’ Routers
Routers are isolated A router engine sees only { input, options } and returns decided | failed; inside the framework it cannot import the graph or agents (ESLint-enforced) and has its own tests
Model providers Every model comes from a @ModelProvider (OpenRouter and the Decisions API built in): timeouts, retries, circuit breakers, costs, reasoning and caching per provider โ†’ Model providers
FinOps built in Every call is recorded (tokens, cache hits, USD, source of the price). Money is capped by @Budget components โ€” per execution, per tenant and for the whole application per day / week / month (UTC), counted call by call in the application's ledger โ†’ FinOps
Typed end to end Strict TypeScript, DTO classes at every boundary, deps checked against constructors, scripted test turns typed by the tool's input
Tested without spending @agboss/core/testing runs a whole workflow with scripted models and the network blocked (Testing); real calls only in make smoke

Run the example

npm install && npm run build          # at the repo root
cd examples/flow-patterns && npm run describe   # every workflow, its paths and inputs โ€” no API key

The job scout (resume โ†’ search brief โ†’ Greenhouse jobs ranked by Jev) is 08-job-scout of agbossjs/agboss-examples: clone it and run its check, test and demo offline at $0.

More: Example (covering agbossjs/agboss-examples 01-hello-agboss .. 08-job-scout, and examples/flow-patterns). npm run studio (repo root) opens flow-patterns in LangGraph Studio โ€” agboss studio in any project, no studio.ts or langgraph.json of its own (CLI).

Public entries

agboss (decorators, DI, flow DSL, settings, environments, observers, judges and decisions, createApp, errors, types), @agboss/core/dto, /units, /models, /testing (+ /testing/setup), and the integrations /mcp, /rag, /a2a, /memory. The older entries are deprecated re-exports; agboss migrate imports rewrites them.

Code map (packages/agboss/src/)

Path What lives there
application/, app/ @Application, createApp(App) โ†’ app.execute / resume / cancel / close; wiring
components/ @Tool @Agent @Injectable @Workflow โ€ฆ, the DI container, assembly
graph/ the flow DSL, assembly rules, LangGraph build, the agent loop, limits, settings
dto/ field decorators, DTO validation, the standard DTOs
routers/ isolated routing engines (Jev, LLM); public inside the framework only via index.ts
models/ model providers
finops/ usage records, cost, daily ledger
testing/ testWith(App), scripted gateway, matchers, VCR
index.ts the root entry agboss

Module dependency rules: Architecture.

Working in this repo

Kind of knowledge Place
Tickets, discussion, specs, implementation plans GitHub Issues
How the system works now this Wiki
Why a significant decision was made Wiki pages ADR-NNNN-โ€ฆ โ†’ ADR
Rules for code, types, agents, FinOps, tests ยท process QUALITY.md ยท WORKFLOW.md ยท CLAUDE.md in the repo
The truth the code

No specs, plans or docs are stored as files in the repository.

Board: Project โ€” stage of every ticket; Done is set by a human.

Branches: production โ† staging โ† dev โ† <type>-<issue> (e.g. feature-12). Work starts and ends in dev through a PR; the gate is make check (build, API reports, compiled docs, format, lint, types, tests with coverage).

Try it: Example.

โš ๏ธ **GitHub.com Fallback** โš ๏ธ