What problem it solves

LLM-powered software must become reliable and maintainable enough for production customers, rather than relying on a generic prompt, tool loop, and framework-driven rewrite. The project addresses the need for engineering principles that give builders deep control while allowing small, modular agent concepts to fit into existing products.

Key features

• A factor-based design guide — The project organizes agent engineering into twelve factors covering prompts, context, tools, state, control flow, errors, human interaction, triggering, and agent design. It also includes a history of software and an additional appendix on pre-fetching context.

  Source: README

• Focus on controllable software — The guide treats capable agents as mostly software with LLM steps at appropriate points, rather than assuming that a generic agent loop is sufficient. It recommends owning prompts, context windows, and control flow so applications can be adjusted deliberately.

  Source: README

• Modular integration with existing products — The guide advocates incorporating small, modular concepts from agent building into an existing product. These concepts are presented as patterns that skilled software engineers can apply without requiring an AI background.

  Source: README

• Practical execution patterns — The factors provide patterns for translating natural language to tool calls, treating tools as structured outputs, unifying execution and business state, pausing and resuming work, and compacting errors into the context window. They also cover triggering agents from anywhere and implementing agents as stateless reducers.

  Source: README

• Open community contribution — The source is presented as public and contributions are invited. The repository includes a discussion thread for contributing to `npx/uvx create-12-factor-agent`.

  Source: README

Quick start

Copied verbatim from the project's README.

initial_event = {"message": "..."}
context = [initial_event]
while True:
  next_step = await llm.determine_next_step(context)
  context.append(next_step)

  if (next_step.intent === "done"):
    return next_step.final_answer

  result = await execute_step(next_step)
  context.append(result)

Who it may suit

This guide may suit software engineers and product builders who want to add agent capabilities to existing applications. It may also suit builders who want deep control over prompts, context, execution, and production reliability.

Topics to discuss

• Which of the twelve factors are most important when adding agent behavior to an existing production product?

• How should teams decide between a generic agent loop and explicit, deterministic control flow?

• What practical patterns should be added to `npx/uvx create-12-factor-agent`?

Written by ReadmeX AI from the project's README, source and public GitHub data; it may contain mistakes.

Read the original README https://github.com/humanlayer/12-factor-agents#readme

ReadmeX opened this community for a trending project; it is not run by the project. Maintainers can claim it from the community page.