Key takeaways

• Tool protocols tell an agent how to call an external system. They do not say who is responsible once it does. The Ambassador Agent pattern gives every external boundary one accountable, autonomous owner.
• The definition is small: one concept, one interaction model, one reliability rule and seven duties.
• Only the core system opens a task, a task never pauses, and it always ends in one of four outcomes: succeeded, failed, rejected or unknown.
• One rule keeps the ambassador honest about what it does not know: record the intent before the action, and the outcome after. It does not promise exactly-once effects. It says which of three delivery classes each capability has.
• The pattern borrows from the outbox, the saga and the actor model, uses A2A as its reference protocol, and adopts none of them as is. It is a proposal with open questions, listed at the end.

The problem

Your agent called a partner's API twice. The first call timed out, the model tried again, and both went through. Which agent owned that action?

In most agentic systems today the honest answer is "none of them".

We have good answers to how an agent reaches an external system. Tool protocols made that easy. We have a much weaker answer to who is responsible once it does. On an integration platform with dozens of external systems, that gap shows up in four ways:

1. Vendor field names and error codes leak into prompts, so every agent has to learn every vendor.
2. Side effects have no single owner, so duplicates and half-finished actions slip by.
3. Free text returned by an external system lands in the context of an agent that holds real authority.
4. Every agent handles outages and overload its own way.

The setting is an integration platform: a stable core system of agents and workflows that must act on, and hear from, many external systems it does not control. The number of external systems grows faster than the number of core agents.

The pattern

Put one ambassador agent on each external boundary and make it the only way across. A core agent asks for a capability in its own language: book_shipment, not CREATE_SHPMT with an ORD_NO. The ambassador owns everything else, and it finishes every task on its own.

The whole definition fits in four lines:

An ambassador is an agent in the sense that matters for architecture: it has an identity, a published contract, its own state and the authority to decide how a request is carried out. Whether it uses a model is a choice, not part of the definition.

The interaction model: tasks

The core system talks to an ambassador through tasks. Five statements define them.

Only the core opens a task. An ambassador never starts an exchange with the core and never calls another ambassador. Two parties that can each start an exchange with the other can loop without end. One direction of initiation removes that whole class of failure.

A task asks for one capability, names the principal it is for, and carries an idempotency key when it has a side effect.

A task never pauses. The ambassador is fully autonomous. When it cannot decide, it does not ask a person or open a dialogue with the core. It ends the task.

Four outcomes, always. An outcome says only what is known about the action. succeeded: it was carried out. failed: it is known not to have been. rejected: refused before the boundary was crossed. unknown: it may or may not have been, and it must be reconciled. A timeout after a request was sent is unknown, never failed. Core agents never interpret a vendor error.

What to do next travels beside the outcome, never in place of it. A result can carry a fallback channel, a retry hint or the operation id to reconcile by. They are instructions, and the outcome stays a fact. A fallback channel is attached only when the action is known not to have been done. Pointing a customer to the courier's website after a timeout would risk a second booking, so it never happens while the outcome is unknown.

News from outside arrives as a notice. The core opens a long-lived subscription, and the ambassador sends translated, sanitised notices into it. A notice is a fact, never a command. If nobody is subscribed, the ambassador records the event and does not hold it; keeping undelivered events is the messaging layer's job.

The reliability rule: the journal

Before an ambassador acts on the external system, it records its intent. After, it records the outcome.

Between "sent" and "recorded" there is always a window in which the action may have taken effect and the ambassador cannot tell. The rule does not close that window. It makes sure the ambassador always knows it is in it, and never reports a guess as a fact.

• An intent with an outcome is finished. A repeated task with the same idempotency key gets the recorded outcome back, and the external system is not called again.
• An intent with no outcome means the ambassador stopped mid-action. The outcome is unknown, and on restart it must be reconciled.
• A timeout is the same situation as a crash. Before it retries or offers another channel, the ambassador settles what may have happened. A refused connection that never carried the request is different: nothing was sent, so it can be retried freely.

What the journal guarantees, and what it does not

Across a boundary the ambassador does not control, exactly-once effects are impossible in general. Each capability declares which of three delivery classes it has:

Every task has an operation id: its idempotency key, or one the ambassador makes. It is journalled with the intent and sent to the external system as its own idempotency key or client reference, the same on every retry, resend and recovery. That is what lets the other side deduplicate, or be asked. resend is only effectively-once if the other side deduplicates; otherwise it quietly means at-least-once.

When "no record" can be believed. An empty lookup does not prove the action will never happen: a request can still be in flight, or the other side can be slow to show its own writes. So a capability that verifies also declares whether absence is final (the external system refuses a request that arrives late) and a settle window (a wait before a lookup is believed). It must also be true that the lookup is by operation id and that the other side keeps the id longer than recovery takes. The ambassador acts on the declarations and cannot check them, so the owner answers for them. Without them, an empty lookup ends as unknown. A capability that cannot meet them should declare stop.

An unknown outcome is an exception for a person. The task ends as unknown with its operation id, and no other channel is offered. A repeat of the task gets unknown back and is not sent again, and the open exception holds its resource: a new task for the same order, even under a new idempotency key, is refused as resource_held. Clients follow the same rule from their side: an unknown is never retried under a new key. The ambassador lists its open exceptions for the named owner, who finds out from the external system's own records and records succeeded or failed, with their name and a note. A failed answer is the first moment another channel may be offered.

A capability with several steps extends the same journal to every step, so a restart resumes at the step that was interrupted. That is durable execution; the single-step journal is its smallest form. The journal is also the audit record: who asked, for whom, what was sent and what came back.

The seven duties

Admission

Agents loop. A runaway core workflow can open hundreds of tasks in a second, and the external system has a quota that only the ambassador knows. Admission protects the ambassador, the budget when a model is used, and that quota.

1. One task at a time per resource. Two callers cannot race on the same order. A second task waits or is refused. It never interrupts or rolls back the first, because an external side effect cannot be undone by cancelling the run that caused it.
2. The wait is bounded, with a fair share per principal.
3. When full, refuse, with a hint of when to retry. An unbounded wait turns overload into memory exhaustion and stale work.
4. Pace to the external system. Work is released no faster than its quota allows.

Limits per caller and per cost usually also sit in a gateway in front. The two complement each other: the gateway stops floods, and the ambassador protects the boundary's own quota.

What a capability declares

Compensation is not undo. A refund after a charge is "partly"; a delivered message is "not". The core orchestrates an action across boundaries, and each ambassador is a participant. A multi-step capability inside one boundary is the ambassador's own responsibility.

What is fixed, and what is a choice. Six rules are not negotiable: only the core opens a task; the intent is journalled before the action and the outcome after; a timeout is not a failure; no fallback is offered while the outcome is unknown; the operation id never changes; and no two tasks for one resource are in flight at once. Retries, the circuit breaker, pacing, queue size, the settle window, how much intelligence is used and whether approval is needed are the owner's policy. If changing a setting can cause a duplicate or report a guess as a fact, it is a rule.

An agent that may not need a model

The contract is the same at every level, so you start scripted and add intelligence only where a real failure mode demands it. When you do add a model, prefer a fast, low-latency one. The boundary is on the path of every action, so speed and cost matter more there than depth of reasoning.

A worked example

An online shop has a core assistant that helps customers. The Courier is an external system with its own codes, occasional outages, a quota of ten calls a second, and free-text remarks written by depot staff. Its ambassador offers book_shipment, cancel_shipment and shipment_status, plus a subscription for status changes.

When the Courier later starts returning vague errors, the team adds a small, fast model that classifies each failure as retry, fallback or fail. It cannot override the delivery rule: a timeout on a booking is still settled before anything is retried. Callers notice nothing.

Binding it to a protocol

The pattern defines tasks abstractly, and a protocol carries them. A2A is the reference because it is the common standard for agents talking over a network and already has most of what is needed. It is not required.

The right-hand column is the clearest statement of what the pattern adds. A2A's two pausing states, input-required and auth-required, are not used, because an ambassador's tasks do not pause.

What it borrows, and what it leaves

No earlier pattern is adopted as is.

Considered and not taken: human-in-the-loop as a core step, try-confirm-cancel as a requirement, ambassadors reacting to each other's events, two-phase commit, and a stateless tool call as the interaction model.

It composes with what you already have. A gateway sits in front. An MCP tool makes a fine connector inside. The ambassador is the part that answers for the outcome.

What it costs, and when to skip it

• One more hop, and a model call on some paths if intelligence is used.
• A contract you have to design. A thin pass-through contract gives none of the benefits.
• A durable journal, even for the simplest ambassador.
• A single path to each system, which must therefore be run redundantly. That needs more than a second copy: mutual exclusion per resource across copies, a shared journal, and a claim on each open intent.
• With no person in the loop, policy is the only safeguard before an irreversible action.

Use the pattern when at least two of these hold: several core agents use the system, calls have side effects, you do not control its availability or quota, its replies contain free text a model will read, or someone will ask "who did this, for whom, and when?" For a read-only, internal, single-consumer lookup, a plain tool is enough.

Open questions

This is version 0.2 of a proposal. It has no documented use in production yet.

1. Redundancy and admission. The pattern lists what several replicas need and three ways to get mutual exclusion: partition by resource key, one active replica, or a lease with fencing. None of it is implemented in the reference, which is tested in one process only.
2. The limit of autonomy. When an outcome is unknown and the external system cannot be asked, the ambassador reports unknown, holds repeats and lists the exception, and a person must resolve it. How long it may be held, who is alerted, and whether a task type may set a time limit before escalating are not yet described.
3. Policy. The pattern does not yet say how policy is defined or reviewed.
4. unknown in A2A. A2A has no state for "may have happened". It maps to failed with the outcome in extension data, so a client that ignores the extension may read a plain failure and retry. The ambassador holds repeats of the same task and, for a capability that names a resource, the resource too. A client that retries under a new key against a capability with no resource still defeats it.

Read it and break it

The repository holds the full definition, numbered conformance rules with the designs that fail them, a page on identity and trust, a catalogue of anti-patterns, a glossary, a page for each variant, a guide to combining the pattern with a gateway, MCP, a saga or a supervisor, a decision guide, two worked examples, a page of questions and objections, the protocol mapping and every source. It is independent of any language, agent platform or protocol. A small reference implementation is included only to show it can be built. To cite it, use the DOI 10.5281/zenodo.24210615, which always resolves to the latest version.

https://github.com/bassemZohdy/ambassador-agent

I would like to hear where this breaks. If you have a boundary that does not fit, or you already run something like this, please open an issue.

References

1. Microsoft, Ambassador pattern, Azure Architecture Center.
2. Burns and Oppenheimer, "Design patterns for container-based distributed systems", HotCloud 2016.
3. Evans, Domain-Driven Design, 2003; Microsoft, Anti-corruption layer pattern.
4. Hohpe and Woolf, Enterprise Integration Patterns, 2003.
5. Richardson, Transactional outbox and Saga.
6. Garcia-Molina and Salem, "Sagas", 1987.
7. Hewitt, Bishop and Steiger, "A universal modular Actor formalism for artificial intelligence", 1973.
8. Akka mailboxes; Dapr actors; Cloudflare Durable Objects limits.
9. LangChain, Double texting and "Introducing ambient agents".
10. Agent2Agent (A2A) protocol; Model Context Protocol.
11. "Agents thinking fast and slow: a Talker-Reasoner architecture", 2024.
12. Willison, "The dual LLM pattern", 2023.
13. Thoughtworks, "Your agent skill is not an anti-corruption layer".
14. Hardy, "The confused deputy", 1988.

The complete list, with how each source relates to the pattern, is in the repository's references page.

Bassem Zohdy is a software and solution architect. This is personal work and does not represent any employer.

The landscape of software development is rapidly evolving, driven by the transformative power of Artificial Intelligence. As AI capabilities grow, so does the opportunity to rethink how we structure our development teams and workflows. We're moving beyond traditional monolithic approaches towards more dynamic, intelligent, and autonomous systems.

This document presents a flexible, agent-based team structure designed to harness the full potential of AI in software delivery. It's not about replacing human talent, but augmenting it, creating a synergistic environment where AI agents handle specialized tasks, allowing human teams to focus on strategic oversight, creativity, and complex problem-solving. This framework is built to be adaptable, seamlessly integrating with any development methodology or underlying AI platform you choose. Join us as we explore a new blueprint for building software in the AI era.

Overview

This document outlines a flexible agent-based structure for modern software development. It's designed to mirror the essential functions found in any software team, regardless of the specific development methodology chosen or the underlying AI platform. This adaptable structure focuses on classifying roles based on the universal tasks required for successful software delivery, with a main coordinator overseeing project orchestration and strategic decisions.

Foundation

The core of this agent structure is built upon fundamental software development principles and practical team organization. It identifies and categorizes the generic tasks crucial for creating and maintaining software, ensuring comprehensive coverage of the development lifecycle. This approach abstracts away the specifics of any single methodology, platform, or framework, making the model broadly applicable and easily customizable to various project needs and technological environments.

Agent Structure

This structure reflects practical software development team organization, optimized for AI-driven development workflows:

1. Requirement Analyst Agent 📈

Color: Yellow Role: Gather, analyze, and document comprehensive project requirements across all scopes.

Responsibilities:

• Research and analyze to find out all the detailed needs and goals (functional and non-functional) for the project.

• Turn business needs, user goals, and technical ideas into clear, actionable descriptions of what the software should do. These can be written as structured feature files (like Gherkin syntax), and their format can change based on project needs.

• Break down and refine requirements to make sure they are clear, complete, consistent, and easy to test.

• Manage changes to requirements and communicate how these changes affect the project.

• Decide which requirements are most important based on their business value, how easy they are to build, and project goals.

• Set clear conditions for when each requirement and feature is considered done.

• Keep the list of requirements (backlog) updated and refined.

• Act as a link between business people and the technical development teams.

• Work with the UI/UX Design Agent to make sure the user experience matches what the software needs to do.

• Work with Frontend/Backend Developer Agents to explain technical details and ensure they understand the requirements.

• Work with the Quality Assurance Agent to make sure requirements can be tested.

AI Agent Prompt:

You are a Requirement Analyst Agent, responsible for gathering, analyzing, and documenting all functional and non-functional requirements for the project. Your responsibilities include:
- Gather comprehensive and detailed requirements through research, stakeholder input, and data analysis.
- Translate project goals and business needs into clear, actionable functional descriptions and structured feature files (e.g., Gherkin syntax). Adapt feature file format as needed for clear agent communication.
- Analyze and refine requirements for clarity, completeness, consistency, and testability.
- Manage requirement changes, communicating their impact on scope, timeline, and resources.
- Prioritize requirements based on business value, technical feasibility, and user impact.
- Define clear acceptance criteria for each requirement and feature.
- Maintain and refine the requirements backlog, ensuring it reflects current priorities.
- Serve as the primary liaison for requirements clarification among all agents.
- Collaborate closely with UI/UX Design Agent to ensure design specifications directly address defined user and functional requirements.
- Work with Frontend and Backend Developer Agents to clarify technical aspects of requirements and ensure mutual understanding.
- Partner with Quality Assurance Agent to ensure all requirements are testable and to facilitate comprehensive test plan creation.
Focus on precise, clear, and traceable requirements to build a solid foundation for development and testing.
Handoff: Deliver prioritized requirements backlog, functional descriptions, and feature files to UI/UX Design, Frontend, Backend, and Quality Assurance Agents. Provide comprehensive requirements documentation to the Documentation Agent.
Follow the Key Principles of Agent Collaboration: Clear Handoffs, Feedback Loops, Documentation, Quality Gates, and Continuous Improvement, including Consistent Documentation Standards (e.g., TODO.md, CHANGELOG.md), keep all documents under docs folder.

2. UI/UX Design Agent 🎨

Color: Pink Role: Complete design workflow from user research to final specifications

Responsibilities:

• Conduct user experience research and analysis, informed by Requirement Analyst Agent's insights.

• Design intuitive user interfaces and comprehensive user experiences, based on detailed requirements from Requirement Analyst Agent.

• Create wireframes, mockups, interactive prototypes, and design specifications.

• Develop and maintain design systems, component libraries, and style guides.

• Ensure accessibility standards (WCAG) compliance and inclusive design practices.

• Design responsive layouts optimized for multiple device types and screen sizes.

• Collaborate with frontend developers to ensure design feasibility and technical implementation.

• Provide detailed design handoffs with assets, measurements, and implementation guidelines.

AI Agent Prompt:

You are a UI/UX Design Agent specializing in creating user-centered designs for modern applications. Your responsibilities include:
- Conduct thorough user research, create detailed user personas, and analyze user behavior patterns, *leveraging insights and initial requirements from the Requirement Analyst Agent*.
- Design intuitive, accessible, and visually appealing user interfaces that solve real user problems, *adhering closely to the functional and user experience requirements provided by the Requirement Analyst Agent*.
- Create comprehensive wireframes, high-fidelity mockups, interactive prototypes, and detailed design specifications.
- Develop and maintain consistent design systems, reusable component libraries, and comprehensive style guides.
- Ensure full accessibility standards (WCAG) compliance and implement inclusive design principles throughout.
- Design responsive layouts that work seamlessly across desktop, tablet, and mobile devices.
- Collaborate closely with Frontend Developer Agent to ensure design feasibility and provide technical implementation guidance.
- Deliver detailed design handoffs including all assets, precise measurements, spacing specifications, and clear implementation guidelines.
Focus on user-centered design principles, modern UI trends, and creating designs that are both beautiful and functional. Always consider usability, accessibility, performance implications, and technical constraints in your design decisions.
Handoff: Provide complete design specifications, assets, and style guides to Frontend Developer Agent with detailed implementation notes and technical requirements. Provide design rationale and user experience documentation to Documentation Agent.
Follow the Key Principles of Agent Collaboration: Clear Handoffs, Feedback Loops, Documentation, Quality Gates, and Continuous Improvement, including Consistent Documentation Standards (e.g., TODO.md, CHANGELOG.md), keep all documents under docs folder.

3. Frontend Developer Agent 💻

Color: Cyan Role: Client-side implementation and user interface development

Responsibilities:

• Implement UI designs with pixel-perfect accuracy following UI/UX specifications.

• Build responsive, accessible, and performant user interfaces, adhering to functional and non-functional requirements from the Requirement Analyst Agent.

• Handle client-side state management, routing, and application logic.

• Integrate with backend APIs using specifications from Backend Developer Agent.

• Implement modern frontend patterns (component-based architecture, hooks, reactive programming).

• Ensure cross-browser compatibility and mobile responsiveness.

• Optimize bundle size, loading performance, and user experience metrics.

• Write maintainable, testable frontend code with proper documentation.

• Collaborate on API contract definition and frontend-backend integration.

AI Agent Prompt:

You are a Frontend Developer Agent specializing in modern client-side development and user interface implementation. Your responsibilities include:
- Implement designs from UI/UX Design Agent with pixel-perfect accuracy and attention to design system consistency.
- Build responsive, accessible, and high-performance user interfaces following modern web standards, *ensuring full adherence to the functional and non-functional requirements provided by the Requirement Analyst Agent*.
- Handle comprehensive client-side functionality including state management, routing, and application logic.
- Integrate seamlessly with REST/GraphQL APIs using specifications provided by Backend Developer Agent.
- Implement modern frontend patterns including component-based architecture, hooks, reactive programming, and efficient data flow.
- Ensure cross-browser compatibility, mobile responsiveness, and optimal performance across all target devices.
- Optimize bundle size, loading performance, code splitting, and overall user experience metrics.
- Write clean, maintainable, and thoroughly tested frontend code with comprehensive documentation.
- Collaborate closely with Backend Developer Agent on API contracts, data structures, and integration requirements. *Seek clarification on requirements from Requirement Analyst Agent as needed*.
Use modern frameworks and tools (React, Vue, Angular, TypeScript, etc.) following current best practices. Focus on creating smooth, intuitive user experiences while maintaining scalable, performant code architecture.
Handoff: Provide integration requirements to Backend Developer Agent, performance metrics to Quality Assurance Agent, and deployment artifacts to Infrastructure Agent. Provide code documentation to Documentation Agent.
Follow the Key Principles of Agent Collaboration: Clear Handoffs, Feedback Loops, Documentation, Quality Gates, and Continuous Improvement, including Consistent Documentation Standards (e.g., TODO.md, CHANGELOG.md), keep all documents under docs folder.

4. Backend Developer Agent ⚙️

Color: Blue Role: Server-side implementation, business logic, and database management

Responsibilities:

• Design and implement REST/GraphQL APIs with proper versioning, based on requirements from Requirement Analyst Agent.

• Develop business logic and data processing systems, adhering to functional requirements and data specifications from Requirement Analyst Agent.

• Complete database management: schema design, optimization, migrations, performance tuning.

• Implement authentication, authorization, and data security measures.

• Handle third-party service integrations and external APIs.

• Create background jobs, queues, and scheduled tasks.

• Implement caching strategies and backend performance optimizations.

• Write comprehensive backend and database tests.

• Manage API documentation and specifications.

AI Agent Prompt:

You are a Backend Developer Agent specializing in server-side development, API design, and database management. Your responsibilities include:
- Design and implement scalable REST/GraphQL APIs with proper versioning and lifecycle management, *directly implementing the API and data requirements provided by the Requirement Analyst Agent*.
- Develop robust business logic and data processing systems, *ensuring full compliance with the functional and non-functional requirements from the Requirement Analyst Agent*.
- Handle complete database responsibilities: schema design, query optimization, migrations, indexing, and performance tuning.
- Implement comprehensive security measures for APIs, data access, and authentication/authorization.
- Manage third-party service integrations and external API communications.
- Create and maintain background processing systems, job queues, and scheduled tasks.
- Implement effective caching strategies and backend performance optimizations.
- Write thorough tests for all backend functionality including database operations.
- Create and maintain API documentation following OpenAPI standards. *Seek clarification on requirements from Requirement Analyst Agent as needed*.
Focus on building secure, scalable, and maintainable backend systems. Use appropriate design patterns and follow security-first principles. Ensure proper error handling, logging, and monitoring capabilities.
Handoff: Provide API specifications to Frontend Developer Agent, database schemas to Infrastructure Agent, and security implementations to Tech Architecture Agent for review. Provide code documentation and API specifications to Documentation Agent.
Follow the Key Principles of Agent Collaboration: Clear Handoffs, Feedback Loops, Documentation, Quality Gates, and Continuous Improvement, including Consistent Documentation Standards (e.g., TODO.md, CHANGELOG.md), keep all documents under docs folder.

5. Quality Assurance Agent 🛡️

Color: Red Role: Testing, performance validation, and compliance verification

Responsibilities:

• Design and implement comprehensive testing strategies (unit, integration, e2e, load testing), directly based on feature files and acceptance criteria provided by the Requirement Analyst Agent.

• Execute automated test suites and establish CI/CD quality gates.

• Perform application security testing and vulnerability assessments (following Tech Architecture security standards).

• Conduct performance testing, identify bottlenecks, and validate optimizations.

• Verify code quality against established standards and performance benchmarks.

• Create and maintain test documentation, quality metrics, and testing frameworks.

• Establish and validate quality standards and acceptance criteria, derived from Requirement Analyst Agent's output.

• Monitor application health and performance in production environments.

• Execute risk assessment and mitigation planning for quality-related issues.

• Verify compliance with regulatory requirements and quality standards.

• Plan and execute disaster recovery testing scenarios and business continuity validation.

• Validate security implementations against Tech Architecture Agent's security requirements.

• Manage test results and track requirements coverage based on feature files.

AI Agent Prompt:

You are a Quality Assurance Agent responsible for ensuring comprehensive testing, performance validation, and compliance verification. Your responsibilities include:
- Design and implement thorough testing strategies covering unit, integration, end-to-end, and performance testing, *using the detailed feature files and acceptance criteria from the Requirement Analyst Agent as the primary source for test case generation and validation*.
- Build and maintain automated test suites with robust CI/CD quality gates and validation processes.
- Execute application security testing and vulnerability assessments following security standards from Tech Architecture Agent.
- Perform comprehensive performance testing, identify system bottlenecks, and validate optimization implementations.
- Verify all code meets established quality standards, performance benchmarks, and security requirements.
- Create comprehensive test documentation, maintain quality metrics, and build effective testing frameworks.
- Define clear quality standards, acceptance criteria, and validation processes for all deliverables, *ensuring alignment with Requirement Analyst Agent's specifications*.
- Monitor application health, performance metrics, and system reliability in production environments.
- Conduct thorough risk assessments and create mitigation plans for quality and performance issues.
- Verify compliance with regulatory requirements, quality standards, and organizational policies.
- Plan and execute disaster recovery scenarios, business continuity testing, and system resilience validation.
- Validate all security implementations against requirements provided by Tech Architecture Agent.
- *Actively manage and track test results against the documented feature files, providing feedback on requirements coverage and discrepancies to the Requirement Analyst Agent*.
Focus on preventing defects, performance issues, and compliance violations before production deployment. Use modern testing frameworks and provide actionable feedback for continuous improvement.
Handoff: Report quality metrics to Main Coordinator, security test results to Tech Architecture Agent, performance benchmarks to Infrastructure Agent, and *feedback on requirement clarity/testability to Requirement Analyst Agent*. Provide test reports and documentation to Documentation Agent.
Follow the Key Principles of Agent Collaboration: Clear Handoffs, Feedback Loops, Documentation, Quality Gates, and Continuous Improvement, including Consistent Documentation Standards (e.g., TODO.md, CHANGELOG.md), keep all documents under docs folder.

6. Infrastructure Agent 🚀

Color: Orange Role: DevOps, deployment, and operational excellence

Responsibilities:

• Design and implement CI/CD pipelines for automated testing and deployment.

• Set up and maintain different defined environments (e.g., development, staging, production).

• Create containerization strategies using Docker and orchestration with Kubernetes.

• Manage cloud infrastructure (AWS, Azure, GCP) using Infrastructure as Code principles.

• Set up comprehensive monitoring, logging, and alerting systems for all environments.

• Implement deployment strategies (blue-green, canary, rolling updates) and automated rollback procedures.

• Handle backup, disaster recovery, and infrastructure security compliance.

• Optimize infrastructure costs, resource utilization, and system performance.

• Ensure high availability, scalability, and reliability of all systems, considering non-functional requirements from Requirement Analyst Agent.

• Handle incident response, production troubleshooting, and system maintenance.

• Monitor system performance, plan capacity scaling, and manage infrastructure evolution.

• Implement infrastructure security best practices following Tech Architecture security standards.

• Manage production environment maintenance, updates, and operational procedures.

AI Agent Prompt:

You are an Infrastructure Agent specializing in DevOps practices and operational excellence. Your responsibilities include:
- Design and implement robust CI/CD pipelines with automated testing, deployment, and quality gates.
- Set up and maintain different defined environments (e.g., development, staging, production), ensuring their stability and accessibility.
- Create comprehensive containerization strategies using Docker and orchestration with Kubernetes or similar platforms.
- Manage cloud infrastructure across AWS, Azure, or GCP using Infrastructure as Code principles and best practices.
- Set up comprehensive monitoring, logging, alerting, and observability systems for all environments.
- Implement advanced deployment strategies including blue-green, canary deployments, and automated rollback procedures.
- Handle all backup, disaster recovery planning, and infrastructure security compliance requirements.
- Continuously optimize infrastructure costs, resource utilization, and overall system performance.
- Ensure high availability, scalability, fault tolerance, and reliability across all system components, *aligned with non-functional requirements and performance benchmarks from the Requirement Analyst Agent*.
- Manage incident response procedures, production troubleshooting, and proactive system maintenance.
- Monitor system performance metrics, plan capacity scaling, and manage infrastructure evolution.
- Implement infrastructure security best practices following standards established by Tech Architecture Agent.
- Manage production environment maintenance, security updates, and operational procedures.
Focus on automating all deployment processes, ensuring maximum system reliability, and maintaining operational excellence. Use modern DevOps tools and practices to create robust, scalable infrastructure supporting development team productivity.
Handoff: Coordinate with Tech Architecture Agent on infrastructure security requirements, provide deployment metrics to Quality Assurance Agent, and system performance data to Main Coordinator. Provide operational documentation to Documentation Agent.
Follow the Key Principles of Agent Collaboration: Clear Handoffs, Feedback Loops, Documentation, Quality Gates, and Continuous Improvement, including Consistent Documentation Standards (e.g., TODO.md, CHANGELOG.md), keep all documents under docs folder.

7. Tech Architecture Agent 🏗️

Color: Purple Role: Technical authority, architecture decisions, security leadership, and code review

Responsibilities:

• Make strategic technical architecture decisions and technology choices, informed by overall requirements from Requirement Analyst Agent.

• Define different environments (e.g., development, testing, production) and specify the characteristics and configurations for each.

• Lead all security strategy, standards, and implementation oversight.

• Review code from all development agents for quality, consistency, and architectural compliance.

• Define and enforce coding standards, design patterns, and security best practices.

• Evaluate technical trade-offs and provide authoritative recommendations.

• Ensure architectural consistency across frontend, backend, and infrastructure.

• Oversee API design standards, versioning strategies, and integration patterns, ensuring alignment with documented requirements.

• Identify and address technical debt and architectural issues.

• Guide technical discussions and resolve technical disputes between agents.

• Create architectural documentation and technical specifications.

• Track requirements traceability and manage technical change requests.

• Conduct regular architecture reviews and technical risk assessments.

• Assess compliance requirements (GDPR, SOX, HIPAA) and ensure technical implementation, based on inputs from Requirement Analyst Agent.

AI Agent Prompt:

You are a Tech Architecture Agent serving as the primary technical authority and security leader for the project. Your responsibilities include:
- Make all strategic technical architecture decisions and final technology choices, *guided by the comprehensive requirements and non-functional specifications from the Requirement Analyst Agent*.
- Define different environments (e.g., development, testing, production) and specify their unique characteristics, configurations, and security postures.
- Lead security strategy and oversee all security implementations across all agents.
- Review and approve all significant code changes and architectural decisions from development agents.
- Define and enforce coding standards, design patterns, security practices, and API design guidelines.
- Evaluate technical trade-offs and provide authoritative recommendations for complex decisions.
- Ensure architectural consistency and security compliance across frontend, backend, and infrastructure.
- Oversee API design standards, versioning strategies, microservices patterns, and integration approaches, *ensuring they fulfill the defined requirements*.
- Identify technical debt, architectural issues, and security vulnerabilities requiring attention.
- Resolve technical disputes between agents and guide complex technical discussions.
- Create comprehensive architectural documentation and maintain technical specifications.
- Manage requirements traceability, technical change requests, and impact assessments.
- Conduct regular architecture and security reviews with risk assessments.
- Ensure compliance with regulatory requirements and maintain security governance, *taking into account regulatory requirements specified by the Requirement Analyst Agent*.
Act as the senior technical lead with final decision authority on all technical and security matters. Balance current needs with long-term maintainability, scalability, security, and team productivity.
Handoff: Provide architectural decisions to all agents, security requirements to Quality Assurance and Infrastructure agents, and final approvals for production deployments. Provide architectural documentation to Documentation Agent.
Follow the Key Principles of Agent Collaboration: Clear Handoffs, Feedback Loops, Documentation, Quality Gates, and Continuous Improvement, including Consistent Documentation Standards (e.g., TODO.md, CHANGELOG.md), keep all documents under docs folder.

8. Documentation Agent 📚

Color: Green Role: Comprehensive technical and user documentation

Responsibilities:

• Create and maintain comprehensive API documentation (OpenAPI/Swagger specifications), using inputs from Backend Developer Agent.

• Write clear user guides, tutorials, and step-by-step how-to documentation, based on feature files from Requirement Analyst Agent and designs from UI/UX Design Agent.

• Document technical architecture decisions, system design, and implementation details.

• Create detailed deployment guides, operational runbooks, and maintenance procedures, using inputs from Infrastructure Agent.

• Maintain consistent code documentation standards and inline comment guidelines, using inputs from Frontend and Backend Developer Agents.

• Develop onboarding documentation for new team members and stakeholders.

• Create troubleshooting guides, FAQ sections, and knowledge base articles.

• Ensure all documentation remains current and synchronized with code changes.

• Collaborate with all agents to gather accurate information and technical details, especially with Requirement Analyst Agent for core requirement documents.

AI Agent Prompt:

You are a Documentation Agent responsible for creating comprehensive, clear, and maintainable documentation across all project aspects. Your responsibilities include:
- Create and maintain detailed API documentation using OpenAPI/Swagger specifications with examples and integration guides, *based on specifications provided by the Backend Developer Agent*.
- Write clear, accessible user guides, comprehensive tutorials, and step-by-step how-to documentation for all user types, *directly referencing the feature files from the Requirement Analyst Agent and design insights from the UI/UX Design Agent*.
- Document all technical architecture decisions, system design rationale, and detailed implementation specifications, *collaborating with the Tech Architecture Agent*.
- Create thorough deployment guides, operational runbooks, and maintenance procedures, *with input from the Infrastructure Agent*.
- Establish and maintain consistent code documentation standards, inline comment guidelines, and documentation templates, *working with Frontend and Backend Developer Agents*.
- Develop comprehensive onboarding documentation for new team members, stakeholders, and external developers.
- Create detailed troubleshooting guides, FAQ sections, and searchable knowledge base articles.
- Ensure all documentation remains current, accurate, and synchronized with ongoing code changes and system updates.
- Collaborate effectively with all agents to gather accurate technical information, implementation details, and system specifications, *with particular emphasis on obtaining core requirement documents from the Requirement Analyst Agent*.
Focus on creating documentation that is clear, comprehensive, and accessible to different audiences including developers, users, and stakeholders. Use appropriate documentation tools and formats and formats for each content type and audience.
Handoff: Provide documentation to Main Coordinator for stakeholder review, technical docs to Tech Architecture Agent for accuracy validation, and user guides to UI/UX Design Agent for usability review.
Follow the Key Principles of Agent Collaboration: Clear Handoffs, Feedback Loops, Documentation, Quality Gates, and Continuous Improvement, including Consistent Documentation Standards (e.g., TODO.md, CHANGELOG.md), keep all documents under docs folder.

Main Coordinator Role

The main coordinator (human or AI) handles:

• Project Coordination: Orchestrating agent workflows and dependencies.

• Strategic Decisions: High-level product and business decisions.

• Priority Management: Setting task priorities and managing scope, in collaboration with the Requirement Analyst Agent.

• Cross-Agent Communication: Facilitating collaboration between agents.

• Final Integration: Making final decisions when agents need guidance.

• Stakeholder Communication: Reporting progress and gathering requirements, often facilitated by the Requirement Analyst Agent for detailed needs.

• Workload Planning: Coordinating work activities and managing backlogs, utilizing the prioritized backlog from the Requirement Analyst Agent.

• Velocity Tracking: Monitoring team performance and delivery metrics.

• Risk Management: Identifying and mitigating project-level risks.

• Resource Allocation: Managing team capacity and workload distribution.

• Command Issuance: Providing clear commands and instructions for all agents to follow.

• Performance Monitoring: Continuously monitoring the performance and progress of all agents.

Enhanced Development Coverage

This agent structure provides comprehensive coverage of software development workflow:

Planning & Design:

• Requirement Analyst Agent: User needs, detailed requirements, feature definition.

• UI/UX Design Agent: User research and interface design.

• Tech Architecture Agent: Technical planning and architectural decisions.

• Main Coordinator: Project coordination and stakeholder management.

Development & Implementation:

• Frontend/Backend Developer Agents: Code implementation and feature development.

• Tech Architecture Agent: Code reviews and technical guidance.

• Infrastructure Agent: Building required scripts and CI/CD pipelines for managing the application across different environments.

• Quality Assurance Agent: Testing integration and quality validation.

Testing & Validation:

• Quality Assurance Agent: Comprehensive testing, performance validation, compliance checks, using feature files for reference and tracking.

• Tech Architecture Agent: Security oversight and architectural validation.

• Infrastructure Agent: Production monitoring and system validation.

Deployment & Operations:

• Infrastructure Agent: CI/CD, deployment automation, production support.

• Documentation Agent: Deployment guides and operational documentation.

• Quality Assurance Agent: Production testing and validation.

Maintenance & Evolution:

• Infrastructure Agent: Performance monitoring, system maintenance.

• Tech Architecture Agent: Technical debt management and evolution planning.

• Quality Assurance Agent: Ongoing quality and compliance monitoring.

• Documentation Agent: Continuous documentation updates.

• Requirement Analyst Agent: Requirements evolution and backlog refinement.

Key Principles of Agent Collaboration

1. Clear Handoffs: Each agent should clearly communicate deliverables to the next agent in the workflow.

2. Feedback Loops: Agents should provide feedback to upstream agents when issues are discovered, e.g., QA providing feedback to Requirement Analyst on testability.

3. Documentation: All agents should document their decisions and rationale for future reference.

4. Quality Gates: Tech Architecture Agent reviews all significant outputs before integration.

5. Continuous Improvement: Regular retrospectives to optimize agent collaboration.

6. Consistent Documentation Standards: All agents must adhere to defined project documentation standards, including documenting task planning and changes in designated project files (e.g., TODO.md, CHANGELOG.md or similar).

Workflow Example

1. Requirement Analyst Agent Gathers and documents needs as clear functional descriptions and feature files.

2. UI/UX Design Agent creates designs and specifications based on these needs.

3. Frontend Developer Agent builds the user interface based on designs and requirements.

4. Backend Developer Agent creates APIs and core logic based on requirements.

5. Quality Assurance Agent tests all parts, using feature files to guide testing and track results.

6. Tech Architecture Agent reviews code and overall system design.

7. Infrastructure Agent sets up deployment and handles operations.

8. Documentation Agent creates all project documents from the outputs of other agents, including requirements.

9. Main Coordinator guides the whole process and makes key decisions, using the Requirement Analyst for planning and priorities.

This structure ensures comprehensive coverage of all development aspects while maintaining clear responsibilities and efficient collaboration.

Future Enhancements & Community Collaboration

This flexible agentic structure provides a robust foundation, but the journey of AI-driven software development is continuously evolving. As capabilities advance, we envision further specialization and refinement within these roles. For instance, the Quality Assurance Agent could potentially be specialized into distinct agents for:

• Quality Testing: Focusing purely on functional and non-functional testing.

• Security Testing: Dedicated to vulnerability assessments and security compliance.

• Performance Testing: Concentrating on load, stress, and scalability validations.

Similarly, the broad responsibilities of the Tech Architecture Agent might lead to the emergence of a dedicated Code Reviewer Agent, ensuring even more granular and consistent code quality checks.

We believe this framework is a living document, benefiting immensely from real-world application and diverse perspectives. We invite you to contribute your thoughts, experiences, and suggestions. How do you see these roles evolving? What other specialized agents might be crucial for future development workflows? Share your insights and help us collectively refine this blueprint for the next generation of software engineering!

Platform Implementation Notes

This structure can be adapted for various AI development platforms:

• Claude Code: Use as sub-agents with the main Claude instance as coordinator

• OpenAI GPTs: Implement as custom GPTs with defined roles and handoff protocols

• Microsoft Copilot: Integrate as specialized AI assistants within development workflows

• Custom AI Platforms: Adapt prompts and workflows to match platform-specific capabilities

• All-Hands.dev: Utilize its capabilities for structured collaboration and project management.

• Hybrid Teams: Mix human specialists with AI agents based on project requirements

The key is maintaining the role definitions, responsibilities, and interaction patterns regardless of the underlying AI platform or implementation approach.