How-To: Serve Ragbits agents for A2A communication

Ragbits agents can be deployed as HTTP servers to enable A2A (Agent-to-Agent) communication. By exposing a FastAPI-based API, agents can receive structured requests, perform reasoning or tool-based operations, and return structured responses — enabling seamless interoperability between agents or external services.

This guide walks through serving a Ragbits agent using FastAPI and Uvicorn, making it compliant with the A2A specification, including the discovery endpoint .well-known/agent.json.

Define the agent

Start by creating a simple weather agent using a structured prompt and tool function:

import json

from pydantic import BaseModel

from ragbits.agents import Agent
from ragbits.core.llms import LiteLLM
from ragbits.core.prompt import Prompt

def get_weather(location: str) -> str:
    """
    Returns the current weather for a given location.

    Args:
        location: The location to get the weather for.

    Returns:
        The current weather for the given location.
    """
    if "tokyo" in location.lower():
        return json.dumps({"location": "Tokyo", "temperature": "10", "unit": "celsius"})
    elif "san francisco" in location.lower():
        return json.dumps({"location": "San Francisco", "temperature": "72", "unit": "fahrenheit"})
    elif "paris" in location.lower():
        return json.dumps({"location": "Paris", "temperature": "22", "unit": "celsius"})
    else:
        return json.dumps({"location": location, "temperature": "unknown"})


class WeatherPromptInput(BaseModel):
    """
    Input format for the WeatherPrompt.
    """

    location: str


class WeatherPrompt(Prompt[WeatherPromptInput]):
    """
    Prompt that returns weather for a given location.
    """

    system_prompt = """
    You are a helpful assisstant that responds to user questions about weather.
    """

    user_prompt = """
    Tell me the temperature in {{ location }}.
    """

llm = LiteLLM(model_name="gpt-4o-2024-08-06" use_structured_output=True)
agent = Agent(llm=llm, prompt=WeatherPrompt, tools=[get_weather])

Generate the agent card

The Agent Card defines the agent’s name, description, and endpoint. It’s automatically served at /.well-known/agent.json and is required for A2A discovery. You can generate the Agent Card using the get_agent_card method:

agent_card = await agent.get_agent_card(
    name="Weather Agent",
    description="Provides current weather for a given location.",
    port="8000",
)

Serve the Agent

To serve the agent over HTTP with A2A-compliant endpoints, use the built-in create_agent_server utility. The agent server exposes two endpoints:

Endpoint	Method	Description
/.well-known/agent.json	GET	Returns the agent's AgentCard metadata
/	POST	Accepts a structured input params: dict and returns the agent's reasoning output

Note

By default, the server runs on port 8000. This can be customized by setting the port parameter when generating the agent card.

To launch the agent as an A2A-compatible HTTP server, run the following code:

import asyncio

from ragbits.agents.a2a.server import create_agent_server

async def main():
    server = create_agent_server(agent, agent_card, WeatherPromptInput)
    await server.serve()

if __name__ == "__main__":
    asyncio.run(main())

This starts a FastAPI-based server on port 8000, serving the agent’s capabilities at the .well-known/agent.json discovery endpoint and handling structured POST / requests in compliance with the A2A specification.