fetchai/innovation-lab-examples

1. This repository is a monorepo of independent agent examples rather than one unified application. The root level mainly provides repository-wide governance, contribution workflow, setup automation, CI, and documentation. The actual runtime architectures live inside many self-contained example folders.

2. The top-level structure is organized by agent framework or integration style: uAgents/Fetch.ai examples, OpenAI/Anthropic/Gemini/Google ADK examples, CrewAI/AG2, MCP agents, A2A integrations, payment-enabled agents, RAG/knowledge agents, and Web3 examples. Each subdirectory is effectively its own deployable unit with its own dependencies and entrypoint.

3. The common application pattern across most examples is a thin startup file plus domain modules. Typical entrypoints are named agent.py, main.py, run.py, or framework-specific variants, and they wire together prompts, tool adapters, state, and communication protocols. This makes the diagram for any single example usually “entrypoint → orchestration logic → tools/services → external APIs.”

4. A major boundary in the repo is agent orchestration versus tool execution. Many examples have dedicated orchestrators, planners, or workflow modules that decide what to do next, while separate modules handle scraping, search, extraction, rendering, or API calls. Examples include multi-agent teams, router agents, and orchestrator/worker patterns.

5. Several examples are explicitly multi-agent systems. For instance, the fetch-hackathon-quickstarter, a2a-uAgents-Integration, Crewai-agents, ag2-agents, and parts of openai-agent-sdk/Appliance Auto Whisperer split responsibilities across specialist agents such as research, analysis, synthesis, or task-specific workers. In diagrams, these should be shown as multiple internal agent nodes coordinated by a central planner or orchestrator.

6. Protocol and transport layers are a first-class architectural boundary in this repo. Many examples define chat, payment, or task protocols in dedicated modules such as chat_proto.py, payment_proto.py, protocols/, or uagents_protocol/. A2A examples add agent-to-agent communication contracts, while MCP examples separate agent logic from MCP server/client adapters.

7. External integrations are usually isolated behind service modules or client wrappers. Common integrations include LLM providers, search APIs, browser automation, financial/payment gateways like Stripe or Skyfire, Google services, GitHub/Gmail/Calendar via MCP, and data sources like NewsAPI, Tavily, Duffel, or BrightData. The repo favors adapters and clients rather than spreading API calls through core agent logic.

8. State management is localized per example and often persistent. Some examples use lightweight in-memory/session stores, while others use SQLite, JSON state files, or dedicated state services. When persistence matters, it is usually used for conversation/session continuity, cached results, payment/session tracking, or agent mailbox/routing metadata.

9. Several examples produce user-facing artifacts rather than just text responses. Examples include card-based news rendering, PDF or report generation, spreadsheet outputs, browser form filling, image/video/music generation, and frontend integration with a Next.js app. In those cases, the pipeline typically ends in a formatter, renderer, or response-composer module that converts internal agent output into a consumable artifact.

10. Testing and packaging are uneven but intentional where examples are more production-like. Some advanced examples include unit/integration tests, Dockerfiles, docker-compose files, and deployment scripts; simpler examples mostly rely on README-driven setup. For architecture diagrams, treat Docker and test artifacts as example-specific deployment/test boundaries, not as shared platform services.

11. The root repo tooling is oriented around contributor workflow and quality gates. GitHub workflows handle CI, label sync/bootstrap, and contributor badges; docs define template/readme standards; and setup.sh plus the root Docker support simplify running a chosen example. This means the repository has a strong governance layer, but no centralized runtime backend.

12. A useful mental model is: “one repository, many small agent systems.” The shared pattern is an agent entrypoint that coordinates domain logic, tool adapters, and external services, with protocols defining how agents communicate and optional state/persistence enabling continuity. Any accurate diagram should therefore be drawn at the example-folder level, not as a single repo-wide service graph.