12-Factor Agents

Why it's ranked here

This is strongest as an architecture checklist, not a drop-in agent framework. The guidance connects abstract concerns to working patterns: structured model outputs, explicit event history, deterministic tool execution, pause and resume behavior, approval gates, and compact agents. That combination makes it useful before a team commits to framework-specific abstractions.

What's good

The project treats model calls as controlled parts of a larger program. It keeps tool execution in deterministic code, makes prompts and context application-owned, joins execution history with business state, and models human approval as another structured interaction. The starter demonstrates both terminal and webhook-driven outer loops, with persisted threads supporting resumed work.

Tradeoffs

The principles require teams to build and own substantial orchestration code. The starter uses filesystem-backed thread storage and integrates with HumanLayer, so it is an example rather than a neutral production stack. Workshop examples also introduce BAML and external model credentials. The supplied material does not establish production storage, deployment, authentication, or operational monitoring.

How to use it well

Use it when designing or refactoring an LLM workflow that needs explicit state, controlled tools, human approval, and multiple entry points. Read the factors as design constraints, then use the starter and workshops to test those patterns in a small workflow. Bring separate infrastructure for production persistence, authentication, deployment, monitoring, and provider selection.

Observed

Licenses

Code is Apache 2.0; content is CC BY-SA 4.0.

Primary language

TypeScript drives the starter agent, server, CLI, workshops, and walkthrough generator; Python supports notebook and repository utilities.

Install surface

Project setup attempts npm install, then Bun or Yarn as fallbacks.

Interfaces

The starter provides a command-line interface and an Express HTTP POST endpoint.

State model

The starter persists event threads with a filesystem-backed store and carries thread identifiers through human-response state.

Test configuration

Jest uses ts-jest, a Node environment, and TypeScript tests located beneath test directories.