# agntcy/coffeeagntcy architecture

> Architecture diagram of the GitHub repository agntcy/coffeeagntcy, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agntcy/coffeeagntcy
- Repository: https://github.com/agntcy/coffeeagntcy

## Overview

CoffeeAgntcy is a developer-facing reference application for demonstrating AGNTCY multi-agent systems, with a smaller Corto setup and a richer Lungo setup. A user submits a prompt through a web UI or agent endpoint; a supervisor orchestrates specialized agents, which can collaborate over A2A and configurable transports to produce a response, sometimes streamed. Lungo also demonstrates MCP weather data, identity, observability, and workflow APIs. Edges reflect README-documented capabilities and the sampled HTTP-to-agent calls; unsampled internal wiring is intentionally not inferred.

Main entry points: [`coffeeAGNTCY/coffee_agents/lungo/api/agentic_workflows/workflows.py`](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/api/agentic_workflows/workflows.py) (Workflow services), [`coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/main.py`](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/main.py) (Logistics supervisor), [`coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/graph/graph.py`](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/graph/graph.py) (Logistics graph), [`coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/auction/main.py`](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/auction/main.py) (Auction supervisor)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_corto["Corto setup"]
  node_corto_ui["Corto web UI<br/>[App.tsx]"]
  node_corto_api["Corto prompt API<br/>[main.py]"]
  node_exchange_agent["Exchange agent<br/>[agent.py]"]
  node_corto_farm["Corto farm<br/>[agent.py]"]
end

subgraph group_lungo_ui_api["Lungo interface"]
  node_lungo_ui["Lungo web UI<br/>[App.tsx]"]
  node_workflow_api["Workflow API<br/>[router.py]"]
  node_workflow_service["Workflow services<br/>[workflows.py]"]
end

subgraph group_supervisors["Workflow supervisors"]
  node_auction_supervisor["Auction supervisor<br/>[main.py]"]
  node_auction_graph["Auction graph<br/>[graph.py]"]
  node_logistics_supervisor["Logistics supervisor<br/>[main.py]"]
  node_logistics_graph["Logistics graph<br/>[graph.py]"]
  node_recruiter_supervisor["Recruiter supervisor<br/>[main.py]"]
end

subgraph group_agents["Specialist agents"]
  node_farm_agents["Regional farms"]
  node_farm_specialist["Logistics farm<br/>[agent.py]"]
  node_shipper["Shipper<br/>[agent.py]"]
  node_accountant["Accountant<br/>[agent.py]"]
  node_helpdesk["Helpdesk<br/>[agent_executor.py]"]
end

subgraph group_shared_services["Shared capabilities"]
  node_mcp_services["MCP services"]
  node_workflow_store[("Workflow instance store<br/>[store.py]")]
  node_identity["Identity service"]
  node_transport["A2A transports"]
end

node_user(("User"))
node_weather["Weather provider"]
node_observability["Observe SDK"]

node_user -.->|"submits prompt"| node_corto_ui
node_corto_ui -.->|"sends request"| node_corto_api
node_user -.->|"submits prompt"| node_lungo_ui
node_lungo_ui -.->|"uses workflows"| node_workflow_api
node_corto_api -->|"executes prompt"| node_exchange_agent
node_exchange_agent -.->|"A2A interaction"| node_corto_farm
node_workflow_api -->|"routes workflow"| node_workflow_service
node_workflow_service -.->|"dispatches workflow"| node_auction_supervisor
node_workflow_service -.->|"dispatches workflow"| node_logistics_supervisor
node_workflow_service -.->|"dispatches workflow"| node_recruiter_supervisor
node_auction_supervisor -->|"builds graph"| node_auction_graph
node_logistics_supervisor -->|"builds graph"| node_logistics_graph
node_auction_graph -.->|"coordinates agents"| node_farm_agents
node_logistics_graph -.->|"coordinates agents"| node_farm_specialist
node_logistics_graph -.->|"coordinates agents"| node_shipper
node_logistics_graph -.->|"coordinates agents"| node_accountant
node_logistics_graph -.->|"coordinates agents"| node_helpdesk
node_farm_specialist -.->|"uses MCP tools"| node_mcp_services
node_mcp_services -.->|"fetches live data"| node_weather
node_workflow_service -.->|"persists instances"| node_workflow_store
node_logistics_supervisor -->|"checks connectivity"| node_shipper
node_auction_supervisor -.->|"configures transport"| node_transport
node_logistics_supervisor -.->|"configures transport"| node_transport
node_auction_supervisor -.->|"traces workflow"| node_observability
node_logistics_supervisor -.->|"traces workflow"| node_observability
node_recruiter_supervisor -.->|"traces workflow"| node_observability
node_workflow_api -.->|"identity features"| node_identity

click node_corto_ui "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/corto/exchange/frontend/src/App.tsx"
click node_corto_api "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/corto/exchange/main.py"
click node_exchange_agent "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/corto/exchange/agent.py"
click node_corto_farm "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/corto/farm/agent.py"
click node_lungo_ui "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/frontend/src/App.tsx"
click node_workflow_api "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/api/agentic_workflows/router.py"
click node_workflow_service "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/api/agentic_workflows/workflows.py"
click node_auction_supervisor "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/auction/main.py"
click node_auction_graph "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/auction/graph/graph.py"
click node_logistics_supervisor "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/main.py"
click node_logistics_graph "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/graph/graph.py"
click node_recruiter_supervisor "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/recruiter/main.py"
click node_farm_agents "https://github.com/agntcy/coffeeagntcy/tree/main/coffeeAGNTCY/coffee_agents/lungo/agents/farms"
click node_farm_specialist "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/logistics/farm/agent.py"
click node_shipper "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/logistics/shipper/agent.py"
click node_accountant "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/logistics/accountant/agent.py"
click node_helpdesk "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/logistics/helpdesk/agent_executor.py"
click node_mcp_services "https://github.com/agntcy/coffeeagntcy/tree/main/coffeeAGNTCY/coffee_agents/lungo/agents/mcp_servers"
click node_workflow_store "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/common/workflow_instance_store/store.py"
click node_identity "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/services/identity_service_impl.py"
click node_transport "https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/common/a2a_transport_config.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_corto_ui,node_corto_api,node_exchange_agent,node_corto_farm,node_user toneBlue
class node_lungo_ui,node_workflow_api,node_workflow_service toneAmber
class node_auction_supervisor,node_auction_graph,node_logistics_supervisor,node_logistics_graph,node_recruiter_supervisor toneMint
class node_farm_agents,node_farm_specialist,node_shipper,node_accountant,node_helpdesk toneRose
class node_mcp_services,node_workflow_store,node_identity,node_transport,node_weather,node_observability toneIndigo
```

## Components

### Corto setup

- [Corto web UI](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/corto/exchange/frontend/src/App.tsx): `coffeeAGNTCY/coffee_agents/corto/exchange/frontend/src/App.tsx`
- [Corto prompt API](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/corto/exchange/main.py): `coffeeAGNTCY/coffee_agents/corto/exchange/main.py`
- [Exchange agent](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/corto/exchange/agent.py): `coffeeAGNTCY/coffee_agents/corto/exchange/agent.py`
- [Corto farm](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/corto/farm/agent.py): `coffeeAGNTCY/coffee_agents/corto/farm/agent.py`

### Lungo interface

- [Lungo web UI](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/frontend/src/App.tsx): `coffeeAGNTCY/coffee_agents/lungo/frontend/src/App.tsx`
- [Workflow API](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/api/agentic_workflows/router.py): `coffeeAGNTCY/coffee_agents/lungo/api/agentic_workflows/router.py`
- [Workflow services](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/api/agentic_workflows/workflows.py): `coffeeAGNTCY/coffee_agents/lungo/api/agentic_workflows/workflows.py`

### Workflow supervisors

- [Auction supervisor](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/auction/main.py): `coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/auction/main.py`
- [Auction graph](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/auction/graph/graph.py): `coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/auction/graph/graph.py`
- [Logistics supervisor](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/main.py): `coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/main.py`
- [Logistics graph](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/graph/graph.py): `coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/graph/graph.py`
- [Recruiter supervisor](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/recruiter/main.py): `coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/recruiter/main.py`

### Specialist agents

- [Regional farms](https://github.com/agntcy/coffeeagntcy/tree/main/coffeeAGNTCY/coffee_agents/lungo/agents/farms): `coffeeAGNTCY/coffee_agents/lungo/agents/farms`
- [Logistics farm](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/logistics/farm/agent.py): `coffeeAGNTCY/coffee_agents/lungo/agents/logistics/farm/agent.py`
- [Shipper](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/logistics/shipper/agent.py): `coffeeAGNTCY/coffee_agents/lungo/agents/logistics/shipper/agent.py`
- [Accountant](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/logistics/accountant/agent.py): `coffeeAGNTCY/coffee_agents/lungo/agents/logistics/accountant/agent.py`
- [Helpdesk](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/agents/logistics/helpdesk/agent_executor.py): `coffeeAGNTCY/coffee_agents/lungo/agents/logistics/helpdesk/agent_executor.py`

### Shared capabilities

- [MCP services](https://github.com/agntcy/coffeeagntcy/tree/main/coffeeAGNTCY/coffee_agents/lungo/agents/mcp_servers): `coffeeAGNTCY/coffee_agents/lungo/agents/mcp_servers`
- [Workflow instance store](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/common/workflow_instance_store/store.py): `coffeeAGNTCY/coffee_agents/lungo/common/workflow_instance_store/store.py`
- [Identity service](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/services/identity_service_impl.py): `coffeeAGNTCY/coffee_agents/lungo/services/identity_service_impl.py`
- [A2A transports](https://github.com/agntcy/coffeeagntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/common/a2a_transport_config.py): `coffeeAGNTCY/coffee_agents/lungo/common/a2a_transport_config.py`

### Other components

- **User**
- **Weather provider**
- **Observe SDK**

## Connections

- User → Corto web UI: submits prompt
- Corto web UI → Corto prompt API: sends request
- User → Lungo web UI: submits prompt
- Lungo web UI → Workflow API: uses workflows
- Corto prompt API → Exchange agent: executes prompt (evidence: `coffeeAGNTCY/coffee_agents/corto/exchange/main.py`)
- Exchange agent → Corto farm: A2A interaction
- Workflow API → Workflow services: routes workflow (evidence: `coffeeAGNTCY/coffee_agents/lungo/api/agentic_workflows/server.py`)
- Workflow services → Auction supervisor: dispatches workflow
- Workflow services → Logistics supervisor: dispatches workflow
- Workflow services → Recruiter supervisor: dispatches workflow
- Auction supervisor → Auction graph: builds graph (evidence: `coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/auction/main.py`)
- Logistics supervisor → Logistics graph: builds graph (evidence: `coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/main.py`)
- Auction graph → Regional farms: coordinates agents
- Logistics graph → Logistics farm: coordinates agents
- Logistics graph → Shipper: coordinates agents
- Logistics graph → Accountant: coordinates agents
- Logistics graph → Helpdesk: coordinates agents
- Logistics farm → MCP services: uses MCP tools
- MCP services → Weather provider: fetches live data
- Workflow services → Workflow instance store: persists instances
- Logistics supervisor → Shipper: checks connectivity (evidence: `coffeeAGNTCY/coffee_agents/lungo/agents/supervisors/logistics/main.py`)
- Auction supervisor → A2A transports: configures transport
- Logistics supervisor → A2A transports: configures transport
- Auction supervisor → Observe SDK: traces workflow
- Logistics supervisor → Observe SDK: traces workflow
- Recruiter supervisor → Observe SDK: traces workflow
- Workflow API → Identity service: identity features
