Getting Started¶

This guide shows how to install and start using Protolink.

The following article on 📝 level-up coding on medium also gives a hands-on guide and overview of Protolink.

Installation¶

Protolink is published on PyPI and can be installed with either uv (recommended) or pip.

Basic Installation¶

This installs the base package without optional extras:

# Using uv (recommended)
uv add protolink

# Using pip
pip install protolink

Optional Dependencies¶

Protolink exposes several extras to enable additional functionality:

uvpipSource checkout

# Install with all optional dependencies
uv add "protolink[all]"

# HTTP support (for web-based agents)
uv add "protolink[http]"

# All supported LLM libraries
uv add "protolink[llms]"

# Development (all extras + testing tools)
uv add "protolink[dev]"

# Install with all optional dependencies
pip install "protolink[all]"

# HTTP support (for web-based agents)
pip install "protolink[http]"

# All supported LLM libraries
pip install "protolink[llms]"

# Development (all extras + testing tools)
pip install "protolink[dev]"

git clone https://github.com/nmaroulis/protolink.git
cd protolink

# Editable install for local development
uv pip install -e ".[dev]"

Optional extras

You usually only need the extras that match your use case. protolink[llms] installs every supported LLM SDK, so production projects may prefer installing only the provider libraries they actually use.

For development from source:

git clone https://github.com/nmaroulis/protolink.git
cd protolink
uv pip install -e ".[dev]"

First Agent¶

Below is a compact example that wires together an agent, HTTP transport, an OpenAI-compatible LLM wrapper, and both native and MCP tools:

from protolink.agents import Agent
from protolink.models import AgentCard
from protolink.tools.adapters import MCPToolAdapter
from protolink.llms.api import OpenAILLM
from protolink.discovery import Registry

# Initialize Registry for A2A Discovery
registry = Registry(url="http://127.0.0.1:9000", transport="http")
registry.start(background=True)

# Define the agent card
agent_card = AgentCard(
    name="example_agent",
    description="A dummy agent",
    url="http://127.0.0.1:8020",
)

# OpenAI API LLM. If model is omitted, OpenAILLM uses its built-in default.
llm = OpenAILLM(model="gpt-4o-mini")

# Initialize the agent
agent = Agent(agent_card, transport="http", llm=llm, registry=registry)

# Add Native tool
@agent.tool(name="add", description="Add two numbers")
async def add_numbers(a: int, b: int):
    return a + b

# Add MCP tools and return them as Protolink native tools
mcp_adapter = MCPToolAdapter(transport="sse", url="https://api.example.com/mcp/sse")
mcp_tools = mcp_adapter.get_tools()
for mcp_tool in mcp_tools:
    agent.add_tool(mcp_tool)

# Start the agent
agent.start()

This example demonstrates the core pieces of Protolink:

AgentCard to describe the agent.
Transport (here HTTPTransport) to handle A2A (agent-to-agent) communication.
LLM backend (OpenAILLM).
Native tools (Python functions decorated with @agent.tool).
MCP tools registered via MCPToolAdapter.

Using the CLI¶

Create a runnable one-file starter agent:

protolink init agent
uv run python agent.py

The default starter uses the top-level API:

from protolink import Agent, AgentCard, LocalTraceTelemetry, Task, create_llm

It runs locally without an API key by executing a tool call directly. If OPENAI_API_KEY is set, it also enables LLM inference. Use --template tool for a tool-only starter or --force to overwrite an existing file.