Skip to content

basic_example

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

basic_example

Folders and files

NameName
Last commit message
Last commit date

parent directory

..
README.md
README.md
 
 
alert_agent.ipynb
alert_agent.ipynb
 
 
registry.ipynb
registry.ipynb
 
 
weather_agent.ipynb
weather_agent.ipynb
 
 

README.md

Basic Example

This directory contains a basic example of how to use ProtoLink to create a multi-agent system with HTTP transport. The example demonstrates:

  • Registry: A central service for agent discovery and registration
  • Weather Agent: An agent that provides weather data
  • Alert Agent: An agent that processes weather data and sends alerts

Files

Architecture Overview

┌─────────────────┐    HTTP REST API   ┌─────────────────┐
│   Registry      │◄──────────────────►│  Alert Agent    │
│  (localhost:    │                    │  (localhost:    │
│   9010)         │                    │   8020)         │
└─────────────────┘                    └─────────────────┘
         ▲                                   ▲
         │                                   │
         │ HTTP REST API                     │ HTTP REST API
         │                                   │
┌─────────────────┐                    ┌─────────────────┐
│ Weather Agent   │◄──────────────────►│  Alert Agent    │
│ (localhost:     │                    │                 │
│  8010)          │                    │                 │
└─────────────────┘                    └─────────────────┘

Getting Started

1. Start the Registry

First, run the registry.ipynb notebook to start the registry service:

from protolink.discovery import Registry

REGISTRY_URL = "http://localhost:9010"

# Create and start registry (uses HTTP transport by default)
registry = Registry(transport="http", url=REGISTRY_URL)
await registry.start()

The registry exposes these endpoints:

  • GET /agents - List all registered agents
  • POST /agents - Register a new agent
  • DELETE /agents/{agent_url} - Unregister an agent
  • GET /status - View registry status and registered agents

2. Start the Weather Agent

Run the weather_agent.ipynb notebook:

from protolink.agents import Agent
from protolink.models import AgentCard, Task

URL = "http://localhost:8010"
REGISTRY_URL = "http://localhost:9010"

class WeatherAgent(Agent):
    async def handle_task(self, task: Task):
        result = await self.call_tool("get_weather", city="Geneva")
        return task.complete(f"Weather data: {result}")

card = AgentCard(url=URL, name="WeatherAgent", description="Produces weather data")
# Using transport type strings - the agent will create HTTP transports internally
agent = WeatherAgent(card=card, transport="http", registry="http", registry_url=REGISTRY_URL)

@agent.tool(name="get_weather", description="Return weather data for a city")
async def get_weather(city: str):
    return {"city": city, "temperature": 28, "condition": "sunny"}

await agent.start(register=True)

3. Start the Alert Agent

Run the alert_agent.ipynb notebook:

from protolink.agents import Agent
from protolink.models import Message, Task
from protolink.transport import HTTPTransport

URL = "http://localhost:8020"
REGISTRY_URL = "http://localhost:9010"

class AlertAgent(Agent):
    async def handle_task(self, task: Task):
        data = task.payload
        if data["temperature"] > 25:
            await self.call_tool("alert_tool", message=f"Hot weather in {data['city']}! {data['temperature']}°C")
        return task

# Using HTTPTransport instances directly (alternate approach)
transport = HTTPTransport(url=URL)
registry = HTTPTransport(url=REGISTRY_URL)

card = {"url": URL, "name": "AlertAgent", "description": "Sends alerts based on data"}
agent = AlertAgent(card=card, transport=transport, registry=registry)

@agent.tool(name="alert_tool", description="Send an alert")
async def send_alert(message: str):
    print(f"ALERT: {message}")
    return {"status": "sent", "message": message}

await agent.start(register=True)

Key Concepts

Registry

  • Purpose: Central service for agent discovery and registration
  • Transport: Accepts either a transport type string ("http") or a Transport instance
  • Endpoints: Provides agent management and status endpoints

Agents

  • Transport: Can use transport type strings ("http") or HTTPTransport instances
  • Registration: Agents can pass registry as a string, transport instance, or transport type with separate URL
  • Tools: Agents can define native tools using the @tool decorator
  • Task Handling: Agents implement handle_task to process incoming tasks

Communication Patterns

  • Agent-to-Registry: HTTP REST API for registration and discovery
  • Agent-to-Agent: HTTP client-server for task delegation and responses
  • Tool Calling: Agents can call their own tools and receive results

Testing the System

Once all agents are running:

  1. Check Registry Status: Visit http://localhost:9010/status
  2. Check Agent Status:
    • Weather Agent: http://localhost:8010/status
    • Alert Agent: http://localhost:8020/status
  3. Send Tasks: Use the Alert Agent to send tasks to the Weather Agent and observe the alert system

Ports Used

  • Registry: 9010
  • Weather Agent: 8010
  • Alert Agent: 8020

Make sure these ports are available before starting the system.