Skip to content

Examples

This section links to example projects and code snippets in the repository.

New here?

Start with the Jupyter Notebooks in examples/notebooks/basic_example! They provide the easiest and best interactive introduction to running the Registry and Agents.

The best way to get started is by running the interactive notebooks in examples/notebooks/basic_example. These notebooks teach you the core concepts of Protolink through a complete multi-agent system:

🎯 What You'll Learn

  • Registry Setup: How to run a central discovery service for agents
  • Agent Creation: Building agents with tools and task handling
  • Agent Communication: How agents discover and communicate with each other
  • Transport Configuration: Using HTTP transport for agent-to-agent messaging
  • Tool Integration: Adding native tools to agents using decorators

📚 Notebook Sequence

Run these notebooks in order to build a complete weather monitoring system:

1. registry.ipynb - Start the Registry

  • Sets up the central discovery service on localhost:9010
  • Exposes REST API endpoints for agent registration and discovery
  • Provides a web interface at /status to view registered agents

2. weather_agent.ipynb - Create a Data Provider

  • Builds an agent that provides mock weather data
  • Demonstrates tool creation with the @tool decorator
  • Shows agent registration and task handling patterns
  • Runs on localhost:8010

3. alert_agent.ipynb - Create a Consumer Agent

  • Builds an agent that processes weather data and sends alerts
  • Demonstrates agent-to-agent communication via the registry
  • Shows different transport configuration patterns
  • Runs on localhost:8020

🏗️ System Architecture

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

🚀 Quick Start

  1. Start the Registry (run registry.ipynb first)
  2. Start the Weather Agent (run weather_agent.ipynb)
  3. Start the Alert Agent (run alert_agent.ipynb)
  4. Test the System: Visit http://localhost:9010/status to see all registered agents

💡 Key Concepts Demonstrated

  • Transport Flexibility: Use transport strings ("http") or HTTPTransport instances
  • Registry Patterns: Pass registry as URL string or Registry object
  • Tool Creation: Native tools with automatic schema inference
  • Task Handling: Implement handle_task for processing incoming tasks
  • Agent Discovery: Find and communicate with other agents via the registry

Example Scripts

The repository includes several standalone example scripts that demonstrate specific Protolink capabilities:

The 0.6.3 examples are small, provider-free scripts intended for application integrators:

  • v063_context_budget.py shows ContextManifest, LLMModelProfile, and enforced RunBudget behavior before a model call.
  • v063_history_compaction.py shows local recent, tokens, and isolated summary compaction plus remote AgentClient.compact_history() over the request-spec endpoint.
  • v063_state_control.py shows client/server state describe, compact, and reset requests for one persistent conversation session.
  • v063_run_reports.py shows RunRecorder, RunReport, RunReplay, golden-run assertions, and redaction.
  • v063_protoagent_policy_mesh.py sketches the ProtoAgent Explorer/Coder/Architect structure abstractly. The prompts are intentionally tiny; the example focuses on tool capabilities, CapabilityPolicy, diff-preview action_builders, and approval-gated workspace writes.

🛠️ devtools_dashboard.py

Purpose: Local devtools, run replay, registry snapshot, and dashboard

  • Uses create_llm("mock"), so it runs without provider credentials
  • Creates several agents and registers their cards in an in-process registry
  • Runs a small task loop and records each streamed run with RunRecorder
  • Saves durable task snapshots and RunReport records to SQLiteRunStore
  • Renders static dashboard HTML using DevtoolsHtmlRenderer, including the disabled Studio preview
  • Prints follow-up commands for protolink run list, protolink run replay, and protolink dashboard
  • Supports --serve-live to start provider-free HTTP agents, an HTTP registry, and the dashboard so ping/chat actions can be clicked
  • The dashboard also contains registry health, selected-agent detail, run replay, and chat panels

📝 basic_agent.py

Purpose: Minimal agent setup focused on core concepts

  • Demonstrates simplified agent creation using dictionary-based AgentCard
  • Shows how to add native tools using the @agent.tool decorator with automatic schema inference
  • Demonstrates direct agent invocation using convenience methods: invoke() and sync.invoke()
  • Includes optional LLM integration for reasoning and inference
  • Uses runtime transport for in-memory execution (no network dependencies)

🧠 agent_memory.py

Purpose: Conversation memory and persistence across tasks

  • Demonstrates the difference between stateless agents (state=None) and persistent agents (state=["conversation"])
  • Shows how sync.invoke() handles session history automatically using a default session_id
  • Demonstrates history persistence across sequential calls to the same agent instance
  • Useful for building conversational bots and multi-turn interaction assistants

🌐 http_agents.py

Purpose: HTTP transport and agent-to-agent communication

  • Demonstrates two agents communicating over HTTP
  • Tests client functions: get_agent_card, send_message_to, call_agent
  • Shows how to set up multiple agents on different ports
  • Includes comprehensive error handling and cleanup

🔒 authentication.py

Purpose: Authentication, credentials propagation, and security verification

  • Demonstrates API key, Basic, and signed Bearer JWT authentication providers
  • Covers server-side route authentication (returning 401 Unauthorized for failed requests)
  • Covers client-side lazy authentication (automatic signature/credential injection on outgoing requests)
  • Verifies both HTTP (Starlette and FastAPI backends) and WebSocket handshake verification
  • Demonstrates success and failure scenarios for both transports

🤖 LLM notebooks

Purpose: LLM backend integration, inference loops, and delegation - Demonstrates direct API LLM usage - Shows infer() with local tool calling - Shows agent_call delegation between agents - Complements the LLM Examples guide

📋 registry.py

Purpose: Registry discovery and autonomous agent behaviour

  • Creates autonomous agents that discover peers and send tasks
  • Demonstrates registry-based agent discovery
  • Shows background task management and cleanup
  • Multi-agent orchestration with automatic peer communication

⚡ runtime_agents.py

Purpose: In-memory agent communication interoperability

  • Uses explicitly mapped URL RuntimeTransport instances for agent-to-agent communication without HTTP configuration
  • Demonstrates safe registry discovery enabling native message parsing safely inside isolated testing contexts
  • Shows how to build reliable agent networks safely running within a single process retaining production semantics
  • Useful for test pipelines scaling native workflow isolation

📡 streaming_agent.py

Purpose: Real-time streaming with progress updates

  • Demonstrates streaming task handlers with progress events
  • Shows artifact production and streaming
  • Context management for multi-turn conversations
  • Event-driven architecture with task status updates

🔌 websocket_basic_example.py

Purpose: WebSocket transport with streaming support

  • Mirrors the basic notebook example but uses WebSocket transport
  • Demonstrates both request/response and streaming task patterns
  • Shows registry discovery over WebSockets
  • Real-time progress updates via WebSocket events

🔄 structured_flows/

Purpose: Advanced flow orchestration patterns

  • Demonstrates Graph flow for complex state machine topologies with cyclic loops
  • Shows conditional branching and multi-step review workflows
  • Examples include sequential processing, parallel execution, and dynamic routing
  • Illustrates integration of multiple agents in structured flow patterns