## Mapping cheat-sheet

| #      | 12-Factor Agent principle             | Where DACA realises it                                                                                                                 | Notes / gaps                                                                                        |
| ------ | ------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| **1**  | **Natural-language → tool calls**     | Agents invoke **MCP servers** as first-class tools; A2A messages can carry tool schemas                                                | Make sure every MCP server publishes a JSON schema so A2A peers can validate calls.                 |
| **2**  | **Own your prompts**                  | OpenAI Agents SDK sits in the *business-logic container*; prompts live in your repo and image layers                                   | Keep versioned prompt files in the same Git tag that builds each Docker image.                      |
| **3**  | **Own your context window**           | DACA’s advice to off-load long-term state to Cockroach/Redis via Dapr lets you send *only* the current slice of context to the LLM     | Add a summariser step in the Dapr Workflow to keep tokens in check.                                 |
| **4**  | **Tools are just structured outputs** | MCP responses are JSON payloads; agents treat them exactly like any other actor message ([github.com][1])                              | Feed those payloads straight back into the event bus—no string parsing.                             |
| **5**  | **Unify execution & business state**  | **Dapr Actors** store the thread plus business data in a single Redis/Cockroach key                                                    | Use the actor ID as your “conversation ID” so replay is trivial.                                    |
| **6**  | **Launch / pause / resume via API**   | FastAPI endpoints (`/agents`, `/events`, `/cancel`) wrap every container; Dapr pub/sub lets a paused agent resume on the next message  | Expose those endpoints through ACA/Kubernetes Ingress so external systems can trigger them.         |
| **7**  | **Contact humans with tool calls**    | HITL flow: agent emits `HumanReviewRequired` → event bus → Chainlit/Streamlit UI → human decision → `HumanDecisionMade` event          | Treat the human gateway itself as an MCP tool so the LLM always emits JSON.                         |
| **8**  | **Own your control flow**             | **Dapr Workflows** express fan-out, retries, and branching, keeping logic in code not prompt spaghetti                                 | Keep the workflow YAML/Python in the same repo as the prompt for traceability.                      |
| **9**  | **Compact errors into context**       | Dapr sidecar auto-retries and raises concise fault events that you can summarise and append to the thread                              | Write a small actor method that trims stack traces to one-liners before feeding them back.          |
| **10** | **Small, focused agents**             | DACA champions *lightweight task-specific containers* and multi-agent collaboration via A2A                                            | Use separate ACA revisions per agent type to scale hot paths independently.                         |
| **11** | **Trigger from anywhere**             | Prototyping stage uses cron-job.org; production uses **Kubernetes CronJobs**, HTTP, or message topics—pick one, same contract          | Keep triggers idempotent: the first event in the Redis stream decides if work is already in flight. |
| **12** | **Stateless reducer design**          | Every agent container is stateless; all persistence lives in Dapr state stores—so `agent(events) → new_event` is a pure function       | Unit-test that reducer locally with an in-mem store to guarantee purity.                            |

---