feat: CoffeeAGNTCY initial docs

docs/.index

@@ -9,5 +9,6 @@ nav:
   - Messaging SDK: messaging
   - Agent Workflow Server: agws
   - CSIT: csit
+  - CoffeeAGNTCY: coffee-agntcy
   - How-To Guides: how-to-guides
   - How to Contribute: contributing.md

docs/coffee-agntcy/.index

@@ -0,0 +1,4 @@
+nav:
+  - Getting Started with CoffeeAGNTCY: get-started.md
+  - Identity in CoffeeAGNTCY: identity-coffee-agntcy.md
+  - SLIM in CoffeeAGNTCY: slim-coffee-agntcy.md

docs/coffee-agntcy/get-started.md

@@ -0,0 +1,80 @@
+# Get Started with CoffeeAGNTCY
+
+
+CoffeeAgntcy is a reference implementation built around a fictitious coffee company to demonstrate how components in the AGNTCY Internet of Agents ecosystem work together.
+
+This project is meant to exemplify how AGNTCY and open-source agentic standards interoperate through clean, reproducible example code. It is purposefully designed for developers across experience levels, from those taking their first steps in building agentic systems to those with more experience curious about AGNTCY's offerings.
+
+With CoffeeAgntcy, you can:
+* How to leverage the AGNTCY App SDK Factory to write transport and agentic protocol-agnostic clients and server code
+
+* Explore SLIM and its support for broadcast and unicast messaging.
+
+* Enable observability with the AGNTCY Observe SDK.
+
+* Learn how to write simple A2A client and server agents
+
+* Orchestrate agents using LangGraph via the supervisor-worker agent architecture
+
+* Understand how to integrate data sources via MCP
+
+
+CoffeeAGNTCY exposes two demo apps: Corto and Lungo. 
+
+### Corto
+
+Corto functions as a minimal demo application. While Lungo expands to showcase the ever-growing ecosystem of agentic tooling, Corto remains intentionally simple, serving as an accessible entry point for developers new to the agentic world or to AGNTCY.
+
+Its role is that of a coffee sommelier: you can ask questions like “What does coffee harvested in Colombia in the summer taste like?” and Corto will respond with a clear, engaging description of its flavor profile.
+
+With just two agents, Corto demonstrates the core patterns of agent-to-agent interaction. A LangGraph-orchestrated supervisor agent acts as an A2A client, connecting to a Q Grader Agent Sommelier (A2A server) over a SLIM transport connection. AGNTCY’s observability tools are integrated via the SDK to provide an end-to-end view.
+
+```mermaid
+flowchart TB
+    A["Supervisor Agent<br/>Buyer"]
+    T(["A2A : SLIM"])
+    B["Q Grader Agent<br/>Sommelier"]
+
+    A <--> T
+    T <--> B
+```
+
+Learn more on how to deploy Corto locally by visiting the [Corto deployment guide](https://github.com/agntcy/coffeeAgntcy/blob/main/coffeeAGNTCY/coffee_agents/corto/README.md)
+
+### Lungo
+
+Lungo is our evolving demo application. As AGNTCY expands, Lungo grows alongside it, adding new features and capabilities, and demonstrating how they work together in an interoperable ecosystem. Like the Corto demo, it includes a LangGraph-orchestrated supervisor agent, but instead of connecting to a single farm, Lungo integrates with three.
+
+Each farm is designed to demonstrate different agentic protocols and implementations. For now, the agents are similar to Corto’s: LangGraph-orchestrated A2A agents that communicate with the exchange using both pub/sub and request–response patterns. The farms are distinguished by "location". In addition to being a A2A server, the Colombia farm acts as a MCP client that connects to a Weather MCP Server.
+
+By default, all agents and MCP servers use SLIM as the transport layer, showcasing its flexibility by switching between one-to-many broadcasts via pub/sub and direct agent-to-agent request–response interactions based on the need specified by the prompt. To learn more about how this works, explore the [CoffeeAGNTCY SLIM Integration](./slim-coffee-agntcy.md)
+
+AGNTCY’s Agent Identity Service handles authentication between agents, allowing them to verify each other’s identity before establishing a connection. This exemplifies the requirement within larger agentic networks for secure communication and trust. To learn more about how this works in Lungo, explore the [CoffeeAGNTCY Identity integration](./identity-coffee-agntcy.md) 
+
+```mermaid
+flowchart TB
+    %% Top
+    S["Supervisor Agent<br/>Buyer"]
+
+    %% Middle transport bus
+    SLIM["SLIM : PubSub or Request Response"]
+
+    %% Farm agents
+    F1["Coffee Farm Agent<br/>Brazil<br/>(Unverified)"]
+    F2["Coffee Farm Agent<br/>Colombia<br/>(Verified)"]
+    F3["Coffee Farm Agent<br/>Vietnam<br/>(Verified)"]
+
+    %% MCP server
+    MCP["MCP Server<br/>Weather"]
+
+    %% Edges
+    S --> SLIM
+    SLIM --> F1
+    SLIM --> F2
+    SLIM --> F3
+    F2 --> MCP
+```
+Learn more on how to deploy Lungo locally by visiting the [Lungo Deployment Guide](https://github.com/agntcy/coffeeAgntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/README.md)
+
+
+

docs/coffee-agntcy/identity-coffee-agntcy.md

@@ -0,0 +1,33 @@
+# Identity in CoffeeAGNTCY
+
+CoffeeAGNTCY uses [Ory Hydra](https://www.ory.sh/hydra) as its identity provider (IDP) within the Agent Identity Service. Ory Hydra is an open-source OAuth2 and OpenID Connect server, which aligns with AGNTCY’s commitment to open, collaborative development. 
+
+The identity flow shown below outlines how CoffeeAGNTCY’s agents authenticate and verify one another through the Agentic Identity Service. before proceeding with collaborative tasks. 
+
+
+```mermaid
+sequenceDiagram
+    participant U as User
+    participant S as Supervisor Agent (A2A)
+    participant I as AGNTCY Identity
+    participant F as Farm Agent (A2A)
+
+    %% Valid badge flow
+    F->>I: Registers as Agentic Application
+    U->>S: Sends order prompt
+    S->>I: Get Farm's Badge Id
+    S->>I: Verify farm's badge
+    I-->>S: Badge is valid
+    S->>F: Sends request to create order
+    F-->>S: Responds with order details
+    S-->>U: Forwards the order confirmation
+
+    %% Separator
+    Note over U,F: -----------------------------
+
+    %% Invalid badge flow
+    I-->>S: Badge is invalid
+    S-->>U: Unable to proceed with this prompt
+
+```
+

docs/coffee-agntcy/slim-coffee-agntcy.md

@@ -0,0 +1,55 @@
+#SLIM in CoffeeAGNTCY
+
+## SLIM in CoffeeAGNTCY  
+
+CoffeeAGNTCY uses **SLIM** (Secure Low-Latency Interactive Messaging) as its default transport layer for all inter-agent communication. SLIM supports both **unicast** (1-to-1) and **broadcast** (1-to-many) messaging patterns, making it well-suited for CoffeeAGNTCY’s dynamic multi-agent workflows.  
+
+The **AGNTCY App SDK** abstracts the underlying SLIM protocol behind a unified factory API. This allows developers to instantiate SLIM-based A2A (agent-to-agent) clients and servers without dealing directly with low-level transport details. Learn more about the App SDK [here](https://github.com/agntcy/app-sdk).
+
+### Instantiating the Factory and SLIM Transport  
+
+```python
+factory = AgntcyFactory("name_of_agent", enable_tracing=True)
+transport = factory.create_transport("SLIM", endpoint=SLIM_ENDPOINT)
+```
+
+Here:  
+- `AgntcyFactory` initializes the factory for the agent.  
+- `create_transport("SLIM", ...)` provisions a SLIM transport instance connected to the configured endpoint.  
+
+### Sending Messages  
+
+SLIM accommodates both targeted and broadcast messaging within the same API:  
+
+#### 1-to-1 Message  
+Used when the supervisor agent needs to send a request to a single farm agent:  
+
+```python
+response = await client.send_message(request)
+```
+
+#### Broadcast Message  
+Used when the supervisor agent sends the same request to multiple farm agents and waits for all (or a subset) of responses:  
+
+```python
+responses = await client.broadcast_message(request, expected_responses=3)
+```
+
+The `expected_responses` parameter defines how many replies the caller waits for before proceeding.  
+
+---
+
+### Example Implementations  
+
+You can explore the CoffeeAGNTCY code to see these concepts in context:  
+
+- **Client implementation** (message sending logic):  
+  [coffee_agents/lungo/exchange/graph/tools.py](https://github.com/agntcy/coffeeAgntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/exchange/graph/tools.py)  
+
+- **Server implementation** (message handling logic):  
+  [coffee_agents/lungo/farms/brazil/farm_server.py](https://github.com/agntcy/coffeeAgntcy/blob/main/coffeeAGNTCY/coffee_agents/lungo/farms/brazil/farm_server.py)  
+
+
+
+
+