AAIF's Five-Project Stack: A Developer's Guide to Open Agent Infrastructure

TL;DR - The Agentic AI Foundation (AAIF) now hosts five projects that cover five different layers of an open agent system. AGENTS.md tells coding agents how to work in a repository. goose is a local, extensible agent runtime. MCP connects agents to tools and data. agentgateway routes, secures, and observes agent traffic. A2A lets independent agents discover one another and exchange work. You can use any one of them, but together they form a surprisingly complete path from a developer's laptop to a governed multi-agent deployment.

I understood AAIF properly only after putting all five repositories next to one another.

From a distance, the project list can look like a bag of agent acronyms. Up close, the boundaries are unusually clean. One project is a Markdown convention. One is a runtime. Two are protocols that point in different directions. One is the network and policy layer around the traffic those protocols create.

That matters because most agent architectures become confusing at exactly those boundaries. Teams ask a tool server to behave like an agent, treat an agent runtime as a protocol, or assume a gateway will fix authorization decisions that the application never modeled. AAIF does not remove the need for architecture. It gives us shared pieces with clearer responsibilities.

As of August 27, 2026, the five hosted projects are:

The first three projects founded AAIF in December 2025. agentgateway joined in June 2026. Agent2Agent, usually shortened to A2A, joined on August 17, 2026 and completed the current five-layer picture. The Linux Foundation reported 247 AAIF member organizations days before the A2A announcement.

This guide is about the engineering model behind that growth, not the member logos.

The mental model: build time and run time#

The easiest way to understand the stack is to separate the system into two time scales.

BUILD TIME

 developer
    |
    v
 goose or another coding agent ---- reads ----> AGENTS.md
    |
    v
 source code, tests, MCP servers, A2A agents, deployment config


RUN TIME

 user or calling service
    |
    v
 orchestrator agent ---- A2A ----> specialist agent
    |                                  |
   MCP                                MCP
    |                                  |
 tools, data, APIs                tools, data, APIs

 Remote MCP, A2A, LLM, HTTP, and gRPC traffic can pass through agentgateway
 for routing, identity, policy, rate limits, telemetry, and resilience.

AGENTS.md mainly shapes the software-development loop. The other four can participate in a running agent system. goose is one possible runtime, not a mandatory runtime. MCP and A2A are protocol boundaries, not orchestration frameworks. agentgateway is a data plane, not an agent brain.

If you keep those sentences true in your design, the stack stays understandable.

1. AGENTS.md: repository instructions that travel with the code#

AGENTS.md is the least complicated project in AAIF and one of the easiest to underestimate.

It is an open format for placing instructions in a file named AGENTS.md, usually at the repository root. Coding agents look for that predictable filename instead of guessing project conventions from a hundred configuration files or expecting every vendor to invent its own instruction format.

A useful file answers the questions a new engineer would ask before changing code:

• What is this repository for?
• Which package manager and commands are canonical?
• Which tests must pass?
• What style and architecture conventions matter?
• Which directories are sensitive or generated?
• Which actions need explicit approval?
• What should a pull request contain?

Here is a compact example:

# Repository guide

## Setup
- Use `uv sync` for Python dependencies.
- Run the service with `uv run app`.

## Validation
- Run `uv run pytest tests/unit` for a focused change.
- Run `uv run ruff check .` before opening a pull request.

## Architecture
- Put protocol adapters under `src/adapters/`.
- Keep domain logic independent of MCP and A2A transports.

## Safety
- Never read or print `.env` values.
- Do not run production migrations without explicit approval.

Why nested files matter#

Large repositories can place additional AGENTS.md files deeper in the tree. The closest applicable file takes precedence, so a monorepo can have a short root policy and precise instructions inside services/billing/, packages/ui/, or infra/.

That is more than organization. It is scope control. A Python service and a React package should not receive the same build commands, test expectations, or risk warnings.

What AGENTS.md does not do#

AGENTS.md is guidance, not an authorization system. It cannot enforce permissions, isolate secrets, verify tool output, or prevent a badly implemented agent from ignoring text. Treat it as the repository's operational contract for agents, then enforce real boundaries through the filesystem, credentials, CI, review rules, and deployment controls.

Use AGENTS.md when you want the instructions to be:

• versioned with the code;
• readable by humans and multiple agent products;
• scoped by directory;
• reviewable in an ordinary pull request.

It is the first AAIF project I would adopt in almost any software repository because it costs very little and improves every later agent interaction.

2. goose: the agent runtime you can run on your own machine#

goose is a general-purpose, open-source AI agent built in Rust. It runs as a native desktop application, a terminal CLI, and an API that can be embedded into other workflows. It supports multiple model providers and connects to external capabilities through MCP extensions.

The simplest installation path for the CLI is the project's release script:

curl -fsSL \
  https://github.com/aaif-goose/goose/releases/download/stable/download_cli.sh \
  | bash

For a controlled environment, inspect the script first or install a pinned release through the method documented for your platform. Convenience should not bypass your software-supply-chain policy.

What the runtime owns#

An agent runtime is responsible for the loop around the model:

1. receive a goal;
2. assemble instructions and context;
3. ask a model what to do next;
4. expose available capabilities;
5. invoke an approved capability;
6. feed the result back into the loop;
7. stop, ask for input, or continue.

goose packages that loop into a usable developer product. Its current project surfaces include:

• desktop, CLI, and API operation;
• support for multiple model providers;
• more than 70 documented MCP extensions;
• reusable YAML recipes for repeatable workflows;
• MCP Apps that can render interactive extension interfaces in the desktop client;
• subagents for isolated parallel work;
• permission controls, sandboxing, and prompt-injection defenses.

Those security features reduce risk, but they do not make every extension trustworthy. An MCP tool still represents code or a remote service with whatever authority you gave it. Review extension sources, scope credentials, and keep destructive actions behind explicit confirmation.

Where goose fits, and where it does not#

Use goose when you want an open local agent for coding, research, automation, data work, or repeatable team recipes. It is also a practical host for testing MCP servers because you can connect an extension and exercise it through a real agent loop.

Do not confuse goose with MCP. goose can use MCP, but MCP clients and servers can be implemented without goose. Do not confuse it with A2A either. A2A connects independently deployed agents across a protocol boundary; a goose subagent is an internal runtime feature.

That distinction preserves portability. Your MCP server should remain usable from another compatible host, and your A2A service should remain callable by an agent built with another framework.

3. MCP: a standard boundary between agents and capabilities#

Model Context Protocol is the agent-to-tool and agent-to-data layer.

An MCP host manages one or more clients. Each client connects to an MCP server that exposes a focused capability. The protocol gives those servers three core primitives:

This is more expressive than reducing every integration to a function call. It also creates clearer control boundaries: a user chooses a prompt, the application decides which resources enter context, and the model may request a tool call that the host can approve or reject.

A current Python server#

The MCP Python SDK v2 supports the 2026-07-28 protocol revision. A complete local server can be very small:

from mcp.server import MCPServer

mcp = MCPServer("inventory")


@mcp.tool()
def stock_for(sku: str) -> dict[str, int | str]:
    """Return available stock for one SKU."""
    # Replace this stub with a narrow service or repository call.
    return {"sku": sku, "available": 12}


@mcp.resource("policy://returns")
def returns_policy() -> str:
    """Return the current returns policy."""
    return "Returns are accepted within 30 days."

Install and inspect it locally:

uv add "mcp[cli]"
uv run mcp dev server.py

The type hints become input schema, the docstring becomes useful capability metadata, and Inspector gives you a direct way to list and invoke the surface before involving a model.

The 2026-07-28 revision matters#

The July 2026 protocol revision made remote MCP easier to scale by moving the HTTP core to stateless requests. It retired the required initialization handshake and session header for that revision, introduced server/discover as an optional capability-discovery RPC, moved Tasks into an extension, and continued the move toward standards-based remote authorization.

Do not read that as "sessions no longer exist anywhere." SDKs still support older protocol revisions, local stdio remains useful, and an application can maintain its own user or workflow state. The important engineering rule is to know which protocol revision your client and server actually negotiate instead of copying an old transport example into a new deployment.

The security boundary is the host, not the schema#

MCP standardizes messages. It does not decide whether a tool call is safe for your user.

For every server:

• expose the smallest useful tool surface;
• validate every argument at the server boundary;
• bind authorization to the real user or workload identity;
• avoid placing credentials in prompts or tool descriptions;
• require confirmation for destructive or high-impact actions;
• log decisions and outcomes without logging secrets;
• treat tool results as untrusted input before they return to a model.

A tool called run_query with unrestricted production credentials is not made safe because its input has JSON Schema. Protocol compliance and least privilege solve different problems.

4. agentgateway: the operational layer around agent traffic#

Once agents move beyond a developer laptop, connectivity becomes an operations problem.

You need to know which agent called which tool, under whose identity, at what cost, with what latency, and according to which policy. You need retries and timeouts that understand long-running agent work. You may need to present several MCP servers as one stable surface or route A2A calls across frameworks and clusters.

agentgateway exists for that boundary.

Its Rust data plane handles HTTP, gRPC, MCP, A2A, LLM-provider, and inference traffic. It can run as a standalone proxy from local YAML or as part of a Kubernetes deployment. In Kubernetes mode, a control plane watches Gateway API and agentgateway resources, translates them into runtime configuration, and sends incremental updates to proxies over xDS.

A small standalone MCP shape#

This illustrative configuration puts two MCP targets behind one gateway surface:

# yaml-language-server: $schema=https://agentgateway.dev/schema/config
mcp:
  targets:
    - name: inventory
      mcp:
        host: http://inventory-mcp:8080/mcp
    - name: orders
      mcp:
        host: http://orders-mcp:8080/mcp

When multiple targets share one MCP backend, agentgateway can federate their tools behind one endpoint. Routing-based configuration is available when you need separate paths, mixed HTTP and MCP backends, or multiple listeners.

What platform teams get#

The useful capabilities cluster into five groups:

• routing: LLM provider routing, MCP federation, A2A backends, service traffic, and self-hosted inference;
• security: TLS, JWT, API keys, OAuth, identity-aware policy, and fine-grained authorization;
• resilience: load balancing, timeouts, retries, health-aware routing, and failover;
• governance: rate limits, token or spend controls, prompt guards, and policy at the traffic boundary;
• observability: OpenTelemetry-compatible metrics, logs, and traces across the data path.

The gateway does not remove application responsibility. A platform policy can block an unauthorized tool, but the tool must still validate business rules. A gateway can attach identity, but a service must still enforce ownership and tenant boundaries. Defense in depth is the design.

When to add it#

You probably do not need a gateway for one local stdio server. You should evaluate one when tools become remote, multiple teams own servers, agents cross trust boundaries, costs need attribution, or production policy must be consistent across frameworks.

Add observability before you need an incident timeline. Agent systems generate multi-hop failures, and a trace is much cheaper than reconstructing the path from five unrelated logs.

5. A2A: a standard boundary between independent agents#

A2A solves the horizontal interoperability problem.

An MCP server exposes capabilities to an agent. An A2A server is an agent endpoint: it can advertise skills, receive a message, create a long-running task, request more input, stream progress, and return artifacts. Its implementation can stay opaque. Callers do not need access to its model, memory, prompt, framework, or internal tools.

Discovery starts with an Agent Card#

An A2A agent publishes a self-describing Agent Card. The standard discovery location is:

curl -sS https://agent.example.com/.well-known/agent-card.json | jq

The card describes:

• the agent's name, description, and version;
• ordered supported interfaces and protocol versions;
• capabilities such as streaming or push notifications;
• input and output media types;
• skills and example use cases;
• security schemes and requirements;
• optional JWS signatures for authenticity and integrity.

Clients choose a compatible interface in preference order. A2A v1.0 defines standard bindings for JSON-RPC, gRPC, and HTTP+JSON/REST while keeping the core data model consistent across them.

The data model is built for work, not chat alone#

The important objects are:

• Message: a unit of communication from a user-side client or an agent;
• Part: text, structured JSON, a URL, or raw file content inside a message or artifact;
• Task: the core unit of action, with an ID, current state, history, and outputs;
• Artifact: a task output composed of one or more parts;
• status and artifact events: incremental updates for streaming or asynchronous work.

A direct question can return a Message. Longer work can return a Task immediately and continue asynchronously. The client can poll, subscribe to a stream, cancel the task, or receive push notifications, depending on the agent's declared capabilities.

A2A does not expose an agent's tools#

That is one of its best design choices.

Suppose a purchasing agent delegates "source 500 units under this budget" to a supplier agent. The caller should not need to know whether the supplier agent queries a database, calls an ERP MCP server, asks a human for approval, or runs a private optimization model. A2A standardizes the promise and the work exchange while preserving implementation opacity.

This is also why wrapping every specialist agent as an MCP tool can be the wrong abstraction. A tool call is usually bounded and capability-oriented. An agent interaction may be conversational, stateful at the application layer, long-running, interruptible, and capable of producing multiple artifacts.

Security still starts with identity#

Agent Cards can advertise API key, HTTP auth, OAuth 2.0, OpenID Connect, or mTLS schemes. Cards may also be signed. Those mechanisms help a client authenticate the endpoint and understand how to call it, but the receiving agent must still authorize every task against the caller, tenant, scope, and business context.

For push notifications, verify the sender, validate task IDs, make handlers idempotent, and assume duplicate delivery can happen. For public cards, never include credentials or private implementation details.

A worked architecture using all five#

Imagine an operations team building an invoice-exception system.

The deployed system has an orchestrator agent, a document agent, and a reconciliation agent. The document agent extracts invoice data. The reconciliation agent compares it with purchase orders and payments. The orchestrator owns the user-facing workflow.

Here is how the AAIF projects fit without overlapping:

1. The repository contains an AGENTS.md file with build commands, test gates, domain boundaries, and a warning that production finance fixtures must never be read during local development.
2. A developer uses goose as a local coding and testing runtime. goose follows the repository instructions and connects to safe development tools through MCP extensions.
3. The team exposes narrow MCP servers for document storage, purchase orders, and payment records. Each server has its own identity and least-privilege access.
4. In production, the orchestrator discovers the specialist agents through their A2A Agent Cards. It sends work over A2A and receives Task updates and artifacts without learning the specialists' internal toolchains.
5. Remote MCP, A2A, and model traffic passes through agentgateway, where the platform team applies identity-aware policy, rate limits, telemetry, and routing rules.

                     A2A                         MCP
 Orchestrator -----------------> Document Agent -------> Document store
      |
      | A2A                                          MCP
      +-----------------------> Reconciliation Agent -------> PO + payments

           [ agentgateway mediates remote protocol and model traffic ]

The architecture remains replaceable at every boundary. The document agent can change frameworks without changing the A2A contract. A storage implementation can change without changing the MCP tool contract. goose can be replaced by another development host. agentgateway can route the same logical traffic to a new environment. AGENTS.md keeps the repository's working contract next to the code throughout those changes.

That is what open infrastructure should buy: not zero migration work, but fewer bespoke integration boundaries.

Do you need all five projects?#

No. AAIF is an ecosystem, not a mandatory framework bundle.

The most common practical sequence is:

1. write AGENTS.md for the repository;
2. build one narrow MCP server and test it with Inspector;
3. use a real host such as goose to validate the human approval flow;
4. introduce A2A only when you have independently deployable agents with a genuine delegation boundary;
5. introduce agentgateway when remote traffic, shared policy, or multi-team operations justify a data plane.

Starting with A2A because "multi-agent" sounds advanced often creates unnecessary distributed-system problems. Starting with one capable agent and well-designed MCP tools gives you a much better baseline. Split into specialist agents when ownership, scaling, security, or independent evolution makes the boundary worth its cost.

A clean fork-and-upstream workspace#

If you plan to contribute across AAIF, keep each project as an independent Git repository. A parent folder is only a container:

aaif/
├── A2A/
├── agentgateway/
├── agents.md/
├── goose/
└── mcp-python-sdk/

Each local repository should point origin at your fork and upstream at the official project:

The repeatable pattern is:

git clone [email protected]:<you>/<fork>.git
cd <fork>
git remote add upstream https://github.com/<official-org>/<repo>.git
git fetch upstream
git remote -v

Do not initialize the parent aaif/ folder as a Git repository. Separate histories, issue trackers, contribution guides, licenses, and release cadences are part of the project boundaries.

Before starting work, read the nearest AGENTS.md, CONTRIBUTING.md, governance document, and test instructions. Then branch from a fresh upstream base. A foundation umbrella does not imply one contribution process.

Production checklist#

Before calling an AAIF-based agent system production-ready, I would want evidence for each of these:

• Repository contract: AGENTS.md accurately names setup, tests, risk areas, and approval boundaries.
• Protocol versions: clients, servers, SDKs, and gateways have explicit compatible MCP and A2A versions.
• Capability scope: every MCP tool and A2A skill is narrow, documented, and backed by server-side validation.
• Identity: calls carry a real user or workload identity across every hop where authorization depends on it.
• Authorization: tools and agents enforce tenant, ownership, role, and action-level policy at the service boundary.
• Human control: destructive, financial, external-message, and irreversible actions have an approval path.
• Secret handling: credentials never enter prompts, logs, Agent Cards, AGENTS.md, examples, or artifacts.
• Network policy: outbound destinations, TLS, retries, timeouts, and rate limits are explicit.
• Observability: traces correlate the user request, agent delegation, model call, tool call, and final result.
• Evaluation: tests cover protocol contracts, tool schemas, task state transitions, refusal paths, and bad inputs.
• Failure behavior: the system can retry idempotently, cancel work, surface partial failure, and avoid duplicate side effects.
• Upgrade plan: a protocol or SDK upgrade is tested in staging instead of being inferred from a package version.

The protocols make interoperability possible. These controls make the resulting system operable.

Where developers can contribute#

Each project rewards a different engineering instinct:

• AGENTS.md: format clarity, compatibility examples, documentation, and the Next.js site.
• goose: Rust runtime work, extensions, providers, recipes, user experience, tests, and documentation.
• MCP: specifications, SDKs, Inspector, reference servers, authorization work, conformance, and examples.
• agentgateway: Rust proxying, Kubernetes control-plane work, routing, policy, observability, inference, UI, and docs.
• A2A: protobuf and specification work, bindings, conformance, SDK examples, interoperability testing, and documentation.

Pick the layer where you already understand the failure modes. A small test that catches a real protocol edge case is usually more valuable than a large first pull request that introduces a new abstraction.

Frequently asked#

What is the Agentic AI Foundation?#

AAIF is a Linux Foundation umbrella for open agent infrastructure and standards. It launched in December 2025 with MCP, goose, and AGENTS.md, then added agentgateway in June 2026 and A2A in August 2026.

How many projects are in AAIF?#

Five as of August 27, 2026: MCP, A2A, AGENTS.md, goose, and agentgateway.

Is MCP the same thing as an agent framework?#

No. MCP is a protocol between an AI application and capability servers. A framework or runtime such as goose can implement the host side, but MCP does not define the agent's reasoning loop.

Are MCP and A2A competing protocols?#

No. MCP standardizes agent-to-tool communication. A2A standardizes agent-to-agent communication. A multi-agent system commonly uses A2A between agents and MCP inside each agent's capability boundary.

Does AGENTS.md control a production agent?#

Not by itself. It is a repository instruction format aimed at coding agents. It improves context and consistency but does not replace sandboxing, authorization, CI, code review, or runtime policy.

Is agentgateway required to use MCP or A2A?#

No. Both protocols can be used directly. A gateway becomes useful when you need shared routing, identity, policy, resilience, observability, or cost controls across remote connections.

Is goose required to build on AAIF standards?#

No. goose is one open runtime in the foundation. MCP and A2A are designed for interoperability across many runtimes, frameworks, SDKs, and vendors.

Which project should a Python developer start with?#

The MCP Python SDK is a direct on-ramp. Build a small server, test it with MCP Inspector, connect it to a host, and contribute only after reading the repository's current issue and pull-request rules. If your interest is agent-to-agent interoperability, the A2A Python SDK and samples are the next logical surface.

References#

• AAIF formation announcement
• A2A joins AAIF's open agentic stack
• AAIF Agent2Agent project page
• Linux Foundation: AAIF grows to 247 member organizations
• AGENTS.md format and examples
• AGENTS.md repository
• goose documentation
• goose repository
• MCP 2026-07-28 release notes
• MCP Python SDK v2
• MCP Python SDK documentation
• agentgateway overview
• agentgateway Kubernetes architecture
• agentgateway MCP configuration modes
• A2A v1.0 specification
• A2A repository
• A2A contribution guide

Written by Aman Mundra - Founder & CEO, Welzin · Co-founder & CEO, CogNerd · ex-PayPal ML.