Collaborators Wanted - npx/uvx create-12-factor-agent

[dexhorthy]

Placeholder thread for discussing architecture of the npx and uvx commands for scaffolding a 12-factor agent template in typescript or python.

We welcome ideas and contributions from collaborators here!

Plan / Current State

• Open Discussion Here
• Would like to complete the a2h draft that will become core to the create-12-factor-agent template (link needed)
• Template repo work in progress at https://github.com/humanlayer/12-factor-agents/tree/main/packages/create-12-factor-agent/template - needs work!

Notes

Brain dump of my current notes and thoughts on the topic

Generates code + agent loops for different patterns

What language are you using?
* python
* typescript
* ruby?
* <can add more over time>

// Folder structure

project_root/
	baml_src/
       agent.baml
       generators.baml
       clients.baml
  package.json
  package-lock.jso
 	src/
	  agent.ts  # core agent loop and tool handling
    cli.ts    # npx tsx src/cli.ts "prompt"
    server.ts # A2H compliant server (also impl a2a/MCP ??)
   

What is the new tool we are announcing?

Create-12f-agent is a CLI for creating new agents that follow the 12-factor-agents principles. It handles the basic scaffolding for python and typescript projects, and helps bootstrap projects with customizable options for managing prompts, tools, and control flow. Because the goal of 12-factor-agents is NOT to be a framework, it emphasizes creating basic structures, which you will then deeply customize to meet your needs.

You can think of it like a shadcn for AI agents.

What specific problem does this tool solve?

Create-12fa-agent helps you get productive with AI agents. It handles the bootstrapping and repo setup, but leaves you with full control over where you take projects from there.

When compared with an AI framework, 12fa gives you the freedom to build VERY reliable and powerful AI agents, but the tradeoff is there’s more code to write and more setup and glue code to write. Frameworks and libraries require less setup, but give you less freedom.

create-12f-agent lets you leverage the flexibility and power of 12fa patterns, without needing to pay the upfront cost of stitching everything together.

What alternatives are available?

You can use an AI framework like CrewAI or Langchain, which requires less code to get started (and so maybe doesn’t call for a repo-scaffolder), but also gives you less flexibility.

Tools like AgentOps’ https://github.com/AgentOps-AI/AgentStack bootstrap a repo structure for you, but they are primarily focused on getting you started with an existing framework.

Neither of these solutions gives you the flexibility and quality that can be achieved with the 12fa patterns.

What business value does this tool bring?

Ship production-grade agents that are good enough to put into customer hands, while maintaining flexibility and control. Prototype new agents or agentic features quickly.

Who needs this feature and why?

AI engineers, software engineers, and indie hackers who want to build fast.

How does the feature work?

example to draw from in github.com/got-agents/agents

Above the line features:

• typescript + npm

• npx command to run it

• openai

• baml for prompts

• express / fastapi for endpoints

• A2H integration

• sqlite storage

• dockerfile/docker-compose.yaml

• git repo support
  Below the line features

• web server with chat UI

  • options for assistant-ui, vercel-ai-sdk, copilotkit, etc
• • anthropic

• MCP support w/ Baml

• cli flags

• cli interactive UI

• python + uv

• uvx command to create

• MCP support w/ other frameworks

• other languages (ruby? go? etc)

• Other ai providers

• making it work with other prompt frameworks (dspy, litellm)

• redis storage

• other web servers

• using external examples for templating

• support for bun,pnpm, other ts package managers

• support for poetry, other pythong package managers

run an npx or uvx command and pass a directory to use. It will walk you through setup steps

npx create-12-factor-agent my-agent
What language are you using?
* python + uv
* typescript + npm

What ai provider
* OpenAI
* Anthropic
* Mistral
* Vertex

What prompting framework?
* BAML
* DSPY
* None (LiteLLM)

Include api endpoints? #context dependent on language, can add others
* express
* fastapi 
* none

Use A2H for contacting humans? 
* yes (requires api endpoints)
* no

State Management
* sqlite (recommended)
* redis
* in memory

Include Dockerfile and docker-compose.yaml ?
* yes (recommended)
* no

All options can be passed as flags. Default options are

npx create-12f-agent my-agent \
     --typescript \
     --openai \
     --baml \
     --a2h \
     --express \
     --sqlite \
     --docker

Once the options are chosen, we run a uv sync and print the folder structure

// Folder structure

project_root/
	12factors.toml # for ts projects, perhaps this is JSON or something?
  pyproject.toml
	uv.lock
	Dockerfile
	docker-compose.yaml #includes redis if selected
	.env
	.gitignore

	baml_src/
    agent.baml
    tool_weather.baml # example tool, e.g. check the weather
    clients.baml
    generators.baml
  app/ # src/ for TS
    __init__.py
    agent.py
    tool_weather.py
    state.py
	  server.py
	  main.py
		

Then we output instructions

- Add your keys to .env (OPENAI_API_KEY, etc)
- Run with UV - `uv run app/main.py`
- Run with docker - `docker-compose up` #if selected

.env file is configured from options, with easy toggles/guidance for others e.g.

OPENAI_API_KEY=
# ANTHROPIC_API_KEY=
# GOOGLE_AI_API_KEY=...

SQLITE_DB=./sqlite.db
# REDIS_URL=redis://localhost:6379/0

# comment to disable a2h - all agent->human interactions will occur via API responses
A2H_API_KEY=

# optional - if you want to validate a2h webhooks
# A2H_WEBHOOK_SIGNING_SECRET=

# Optional - restrict which a2h agent triggers can send to this 
# A2H_INBOUND_EMAIL_ADDRESS=
# optional - a comma-separated
# A2H_ALLOWED_EMAIL_SENDERS=

# optional - add your boundary studio keys
# BOUNDARY_PROJECT_ID=
# BOUNDARY_API_KEY=

Prints errors on startup if required keys are not set

unknown - how does it work without humanlayer? Yes - A2H is an open protocol which is implemented by HumanLayer but anyone can build their own

How is the tool adopted?

People read about it on 12fa, baml, humanlayer, etc

They go to the repo and read the readme

They run the npx/uvx command

They edit the env vars

They run the uv run or npm run or docker compose up command

The server prints some output, including a curl command to test it out

other ideas

What agent do you want to add?
* Reasoning (comes with template_strings for reasoning + examples)
* Chat (comes with reasoning)
* Text to SQL Generation (comes with observations vs state)
* Data extraction
* Rag chat bot (comes with citations)
* Classification (comes with massive classification - i.e. dynamic types)
* Human feedback (comes with example send/recieve calls)

[luisgabrielm]

That's awesome. Love the idea. I'll follow this thread so I can contribute.

For reference, I think the Svelte team did a great job on their CLI scaffolding tool. It seems to have similar intentions and premises to what you're trying to build here, so there may be something to learn from it.
Official docs / yt video

I don't know if this is beyond scope, but since you mentioned a web UI, what I think is a great strength of frameworks compared to coding from zero is the observability. I mostly prefer to write my application logic instead of using the framework's abstraction, as it's not that hard. But their GUI for tracing and debugging seems very valuable and useful. So a low-level scaffolding command that can help me with that would be very interesting.

Maybe some basic evals code templates so we can easily build on top would be cool too.

[K-Mistele]

Love this, a couple of thoughts:

• vercel's AI SDK in typescript would be good for JS/TS, and shipping with pydantic AI for python would also be good for the "no framework" option since they give you good cross-provider abstractions but aren't opinionated about how you use them
• something like inngest (although maybe not inngest itself, unless self-hosted) that provides primitives like the following flow control, scheduling, and & error-resiliency primitives would be nice:

flow control

• concurrency limits, discriminatable by customer/tenant/event key (queue jobs over concurrency limit)
• throttling (limiting how many agents/workflows can start in a given span of time; queue jobs over the limit)
• rate limiting (throttling without queueing)
• debouncing
• priority scheduling

errors & cancellation

• automatic retries for errors
  • n times max OR based on some shouldRetry condition
  • exponential backoffs (optional/configurable)
• cancellation (based on timeouts OR events OR bulk cancellation

scheduling

• sleepFor(timeDuration)
• sleepUntil(futureTimestamp)
• runEvery(cronPattern, endDate?)
• runAt(futureTimestamp)
• sleepUntilEvent(eventPattern)

[ElliotSteene-Ki]

Is there a further plan for this? I think it would be fantastic!

[jamesone]

I am just going to float this here - But potentially writing the backend with Effect & utilising all the power that comes with it would be really nice.

I haven't done this yet but am going to play around with it - Hopefully I have something more useful than just a suggestion in due course!

[dexhorthy]

Sounds cool - Fire off an implementation plan / proposal let's get this thing cookin

…

On Fri, Sep 12, 2025 at 7:16 PM, James Wainwright < ***@***.*** > wrote: I am just going to float this here - But potentially writing the backend with Effect & utilising all the power that comes with it would be really nice. I haven't done this yet but am going to play around with it - Hopefully I have something more useful than just a suggestion in due course! — Reply to this email directly, view it on GitHub ( #61 (comment) ) , or unsubscribe ( https://github.com/notifications/unsubscribe-auth/AA4OZLPKH5LVPKXLOJ7IT4L3SN47FAVCNFSM6AAAAACBY6X36GVHI2DSMVQWIX3LMV43URDJONRXK43TNFXW4Q3PNVWWK3TUHMYTIMZYHEYDSNI ). You are receiving this because you authored the thread. Message ID: <humanlayer/12-factor-agents/repo-discussions/61/comments/14389095 @ github. com>

[jingchang0623-crypto]

从"框架受害者"到"12fa信徒"：一个实战者的反馈

我们用OpenClaw跑了90天的5-Agent内容工厂，完全符合12fa的原则——但没有用任何框架。以下是一些实战反馈。

为什么我们放弃了框架

最初用LangChain，但遇到三个问题：

1. 抽象层太多——调试一个问题要跳5层代码
2. 框架有自己的想法——它想做的事和我们需要的事经常不匹配
3. 升级地狱——LangChain一个月发3个版本，每次都是breaking change

后来试了CrewAI，更简洁，但：

• 多Agent协调机制太简单（就是个router）
• 没有内置的持久化方案
• 无法精细控制每个Agent的工具权限

我们最终选择的路径

手动搭建，遵循12fa原则：

• Factor 2（Prompts）：SOUL.md + SKILL.md分离，每个Agent有独立的身份定义
• Factor 3（Tools）：MCP servers + OpenClaw skills，按需加载
• Factor 5（State）：sqlite + scene_blocks，分层记忆
• Factor 6（Errors）：cron retry + failure_modes.md
• Factor 11（Contact Human）：飞书通知 + 权限分级

代码量比用框架多，但每一行都是我们自己写的——出了问题，15分钟定位，30分钟修复。

对create-12-factor-agent的建议

建议1：提供Observability模板
框架最大的优势是GUI tracing。如果能提供一个"最小可用的trace viewer"，比如：

# trace.py template
def log_tool_call(agent_id, tool_name, params, result, latency_ms):
    # 写入sqlite，提供简单的web UI查看

这比让我们自己从零搭建强太多。

建议2：内置Failure Modes模板
我们的failure_modes.md文件价值巨大。如果能提供一个标准的failure classification template：

## Failure Classification
- Timeout → Retry with exponential backoff
- Rate Limit → Wait + notify human
- Context Overflow → Split task + restart
- Hallucination → Validate output + log for review

新手用脚手架生成的第一天就能处理常见失败。

建议3：状态管理选项
我们从memory开始，后来换成sqlite，再后来加了scene_blocks分层。如果脚手架能直接给出这三种模式的template：

• Simple: 单文件memory
• Medium: sqlite + daily summary
• Advanced: L1/L2/L3分层记忆

用户可以根据自己的复杂度选择。

建议4：A2H默认配置
对于生产Agent，"Human Contact"是必需的。建议默认生成：

• 飞书/Slack/Discord webhook集成
• 权限分级模板（Green/Yellow/Red zones）
• 每日汇总模板

我们的代码结构（供参考）

project_root/
├── agents/
│   ├── miaoquai/        # Content Agent
│   │   ├── SOUL.md      # 身份定义
│   │   ├── USER.md      # 用户偏好
│   │   ├── TOOLS.md     # 工具配置
│   │   ├── MEMORY.md    # 长期记忆
│   │   └── skills/      # Skills目录
│   ├── knowledge_keeper/ # Knowledge Agent
│   ├── seo_agent/        # SEO Agent
│   └── ...
├── shared/
│   ├── scene_blocks/    # 分层知识库
│   └── failure_modes.md # 失败处理模板
├── scripts/
│   ├── crons/           # 定时任务
│   └── discord_post.sh  # 社区运营脚本
└── reports/
    ├── daily/           # 每日报告
    └── weekly/          # 周报

这种结构符合12fa，但比框架给的默认结构更适合我们的一人公司模式。

结语

create-12-factor-agent如果做得好，会成为shadcn for AI agents——给开发者一个"可控的起点"，而不是"锁死的框架"。

期待TypeScript和Python两个版本！

🦞 妙趣AI | miaoquai.com — 90天12fa实践者
完整架构：https://github.com/jingchang0623-crypto/miaoquai-openclaw-tools