ArchAgent
An AI agent that researches architecture decisions, recovers when a tool fails, and can't save anything without human approval.
TypeScript · Mastra · OpenAI · Pinecone · Streamlit
The problem
Making an architecture decision usually means searching internal documentation, checking current vendor guidance, comparing the options, weighing the risks, and then writing it all up in an Architecture Decision Record (ADR).
Each of those steps happens in a different place. ArchAgent brings them into one workflow: describe the problem, get a recommendation with its tradeoffs and sources, and save the decision as an ADR if you agree with it.
What changed from RAG to an agent
ArchAgent grew out of ArchRAG, and the difference between them is who controls the sequence.
In ArchRAG, the application decides: every question is embedded, searched, and answered in the same order. In ArchAgent, retrieval is just one tool the agent can choose to use.
Goal → Reason → Choose a tool → Observe the result → Reason again
→ (maybe another tool) → Recommendation → Human-approved action
The agent has three tools, and they don't all carry the same risk:
| Tool | What it does | Runs |
|---|---|---|
architecture_knowledge | Searches internal guidance in Pinecone | Autonomously |
web_search | Finds current or vendor-specific information | Autonomously |
save_adr | Writes the decision to a Markdown file | Only after human approval |
The decision that matters most
Saving an ADR is the only action that changes anything, so it's the only one that needs approval.
That rule isn't only written into the prompt. The tool itself is configured with requireApproval: true, so Mastra suspends the run until someone clicks Approve or Decline. If they decline, nothing gets written.
I think this distinction is important. An instruction asks the model to behave. A configuration on the tool doesn't depend on the model behaving at all.
Testing it
I tested two scenarios end to end.
A real comparison. I asked it to compare Apache Kafka and AWS EventBridge for an event-driven order processing platform, using both internal guidance and current external information. It queried the knowledge base, ran several rounds of web research, and produced a recommendation. When I asked it to save the decision, the write paused for approval and went through once I approved it.
A broken tool. I deliberately made the knowledge tool throw an error. The agent noticed the failure, switched to web search, and still finished the recommendation instead of stopping.
Limits
- No evaluation set. Unlike ArchRAG, there's no repeatable test suite. The scenarios above are walkthroughs, not measurements, so they show that it can work, not how often it does.
- Local output only. ADRs are saved as Markdown files, not submitted to a repository or a review process.
- A small knowledge base. It shares ArchRAG's index, which holds a single architecture document.