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)