CoffeeAgntcy + agntcy_app_sdk notes

corto

# CoffeeAgntcy & app-sdk

Communication:
   Exchange --- SLIM ----  Farm
      (A2A)                (A2A)
            topic = "{farm_agent_name}_{farm_agent_ver}"

## Transport setup

- for farm and exchange agent instances:
  - config var settings
    - DEFAULT_MESSAGE_TRANSPORT = "SLIM"
    - TRANSPORT_SERVER_ENDPOINT = URL of slim server, e.g. http://slim:46357

- Reference:  app-sdk-->agntcy_app_sdk :: AgntcyFactory :: create_transport()

Code:
- exchange --> graph.py::ExchangeGraph::build_graph() @graph("exchange_graph")
                 +->  new FlavorProfileTool( remote_agent_card=farm_agent_card, )
                       - farm_agent_card = from farm.card import AGENT_CARD
                          - card has name, ID, description, endpoint URL, capabilities, skills
                       - given to langgraph as a tool attached to the agent get_flavor_profile_a2a_agent
    |
    +--> FlavorProfileTool
         ::connect() method creates Agntcy transport & A2A client
           |
           +-> get_factory() -- returns the agntcy factory created in ::main()
           +-> transport = factory.create_transport(
                  DEFAULT_MESSAGE_TRANSPORT,  # this is an enum value of agntcy_app_sdk::factory.py::TransportTypes -- default = SLIM
                  endpoint=TRANSPORT_SERVER_ENDPOINT,  # SLIM server endpoint
               )
           |
           +-> create a pubsub topic from an app card:  agntcy_app_sdk/protocols/a2a::A2AProtocol.create_agent_topic(self._remote_agent_card)
                |
                +->util that concats the app name and version
           |
           +-> create agntcy transport client:  agntcy_app_sdk::factory.create_client( protocol = "A2A",
                                                                                       topic,
                                                                                       agent_url = farm agent URL, # not used for SLIM
                                                                                       transport = transport)
                - pubsub client to SLIM for farm agent topic
                   +-> agntcy_app_sdk::a2a/protocol.py:: A2AProtocol::create_client()
                       - for transport = SLIM uses only topic and transport obj to create client for SLIM server pubsub
                       |
                       +-> agntcy_app_sdk::a2a/protocol.py:: A2AProtocol::get_client_from_agent_card_topic(topic)
                           - Gets an A2A agent card from the topic  (A2A SDK obj AgentCard)
                             |
                             +-> publishes a GET message type to the topic with the path = ".well-known/agent.json"
                                 |
                                 +-> apparently the farm agent will respond with an A2A agent card
         
        :: send_message( prompt ) method
           |
           +-> constructs request message --> see a2a.types SendMessageRequest
           |
           +-> uses pubsub client (agntcy_app_sdk) to send message and handle response
          

- farm --> farm/farm_server.py:: main()
  |
  +-> server = create a A2A app and request handler for FarmAgent()
       - obj type =  A2AStarletteApplication
  |
  +-> agntcy_app_sdk::factory.create_transport(
            DEFAULT_MESSAGE_TRANSPORT,
            endpoint=TRANSPORT_SERVER_ENDPOINT,
        )
  |
  +-> bridge = agntcy_app_sdk::factory.create_bridge(server, transport=transport)
       - creates pubsub client for server side receiver of SLIM messages
       - does special topic creation using local server agent card for server type == A2AStarletteApplication
         - performs A2A ingress handler creation
       - bridge obj reference agntcy_app_sdk::bridge.py::MessageBridge
  |
  +-> agntcy_app_sdk::bridge.start(blocking=True)
      - sets message handler
      - subscribes to topic 
      

lungo

Lungo Communication:
                                  [Farms]
   Exchange --- SLIM + A2A  ----  Brazil
                            ----  Columbia   --- SLIM + MCP --- weather_service (MCP server)
                            ----  Vietname

       SLIM topic = FARM_BROADCAST_TOPIC (env config var, default = "farm_broadcast")

       NOTE: each farm server also listens on a SLIM topic specific to itself (in addition to the broadcast topic)


  SLIM + MCP example (NOTE: not currently working with SLIM--https://github.com/agntcy/app-sdk/issues/25):
   +-> coffeeAGNTCY/coffee_agents/lungo/farms/colombia/agent.py::FarmAgent::_get_weather_forecast()
        |
        +->factory.create_transport(transport=DEFAULT_MESSAGE_TRANSPORT, endpoint=endpoint)
            - SLIM transport but with endpoint = f"{WEATHER_MCP_SERVER_URL}/mcp"
        |
        +--> client = agntcy_app_sdk::factory.create_client( protocol = "MCP", endpoint_url = f"{WEATHER_MCP_SERVER_URL}/mcp", transport)
              |
              +-> sets up a MCPProtocol obj
              |
              +-> creates a MCPProtocol client
                  - looks like currently it's just creating a StreamableHTTPTransport() and not doing anything with the SLIM transport
        |
        +-> client.session.list_tools()
            - gets list of tools from MCP server