Hi everyone,

I wanted to share a project I've been working on called Protolink (https://github.com/nMaroulis/protolink). I’d love to get some honest feedback from this community on the approach I took.

The Honest Start: Why I Built This

I’m not going to start with the typical "I got tired of LangChain/LangGraph so I built something better" pitch. The truth is, I read through Google's Agent-to-Agent (A2A) protocol specification and loved the philosophy, to treat agent communication as structured, typed, and decoupled distributed messages.

However, when I actually sat down to build a multi-agent system using raw A2A guidelines, I realized how much infrastructure boilerplate I had to write:

• Setting up separate client and server applications for every single agent.
• Manually handling discovery and registry lookups.
• Wiring up LLM inference loops, parsing raw JSON, and writing tool-calling logic (especially fallback modes for smaller, local models that don't support native tool calling).
• Orchestrating tasks without a clean runtime state-machine model.

So, I started building Protolink. I wanted to see if I could create adeveloper-first, A2A-native agent runtime that abstracts away all the network and LLM boilerplate while remaining fully compliant with the protocol.

How Protolink Extends A2A with Runtime Context

In Google's A2A spec, details like LLM invocation, tool execution, and local-versus-remote transport are largely out of scope. Protolink extends the spec by unifying them into a single, cohesive runtime concept: the Agent.

1. Unified Agent Model: Instead of maintaining separate client and server codebases, a Protolink Agent contains both a client and a server. It owns its lifecycle, storage, and transport layer.
2. First-Class LLM & Tool Loops: Protolink manages the LLM inference loop. It takes care of mapping schemas to different model APIs (OpenAI, Anthropic, Gemini, Ollama) and handles JSON fallbacks for smaller models.
3. In-Process transport (runtime): This is probably the biggest quality-of-life feature. Running multiple agents across separate HTTP/WebSocket servers during local development is a headache. Protolink implements an in-process, shared-memory transport. You can run and test an entire agent mesh in a single Python process. When you're ready to deploy, you change transport="runtime" to transport="http" or transport="websocket" in the config, where no agent logic changes required.

The Runtime Layer: Managing the execution Lifecycle

While A2A defines what travels through the system (the payload: Task, Message, Artifact, Part), a real-world application needs to control how it executes. Protolink introduces a structured runtime layer that wraps execution with stable security, monitoring, and control boundaries:

• RunContext (Typed Execution Envelope): Ad hoc metadata keys like session_id, trace_id, and workspace_uri are replaced with a single serializable object. When tasks are delegated downstream, RunContext.child() automatically propagates workspace paths, trace IDs, permission boundaries, and run budgets (max_steps, max_llm_calls) while establishing parent-child relationships.
• Cooperative Cancellation: Interrupting long-running asynchronous tasks (especially multi-agent loops or streams) is notoriously tricky. Protolink handles cancellation at the runtime level. Calling client.cancel_task() propagates a cancellation state through HTTP/WebSocket/Runtime transports, and the local agent triggers a process-safe CancellationToken checkpoint. It stops CPU loops, async tool calls, or model streams gracefully at the next await boundary without losing task execution history.
• Capability Policies & Human-in-the-Loop Approvals: We normalize all LLM decisions into a provider-independent RunAction before any side effects happen. If an action requires a protected capability (e.g., records.write), the CapabilityPolicy evaluates it. If it requires approval, the agent pauses, creates an ApprovalRequest with preview artifacts (so users see exactly what will write to disk or database), and triggers an application-level handler (like a CLI prompt or a web UI modal) before executing.
• Normalized Event Streams (RunEvent): Transports can emit messy, custom events. Protolink wraps these into a single versioned RunEvent stream (e.g., action.requested, approval.required, task.status, llm.stream) sent to an EventSink. This means terminal UIs, log aggregators, or telemetry monitors can switch on a unified schema regardless of the underlying LLM provider.

Structured Flows Using A2A Primitives

Most agent frameworks use external graph engines (like LangGraph or custom DAG builders) to coordinate agent interactions. In Protolink, I wanted the workflow orchestration to remain protocol-native.

A Protolink Structured Flow is a deterministic state machine that operates directly over A2A primitives: Task, Message, Artifact, and Part. The flow orchestrator expects a Task and returns a Task.

We support several topologies out of the box:

• Pipeline: A sequential chain of agents.
• Parallel: Broadcasting tasks to concurrent agents with safe ID-based fan-in merging to prevent duplicate artifacts.
• Router: Conditional branching based on structured, serializable Part.route(...) decisions.
• Graph: Full state-machines that support loops and cycle back on validation failures.

🧠 The Secret Sauce: Semantic Context Injection

How do you run structured flows without tightly coupling the agents to the flow topology?

We use Dynamic Semantic Context Injection:

1. Before sending a task to an agent, the Flow orchestrator looks at the downstream step in the topology.
2. It fetches the downstream agent's description and capabilities (AgentCard) from the Registry.
3. It dynamically builds a system prompt (e.g., "Your output will go to the 'Summarizer' agent, which expects X formatting" or "You are broadcasting to a committee of ['Editor', 'Security_Inspector']") and attaches it to the Task's flow_state.
4. The executing agent automatically merges this prompt into its system prompt during LLM inference, adapting its output layout at runtime to suit the downstream consumer.

Cool Usages: What Can You Build?

Here are two cool examples of what this looks like in practice:

1. A Local "Claude Code" Clone (~3 Agents)

I built a mini "Claude Code" coding assistant by composing three specialized agents:

• Orchestrator Agent (Coordinator): Receives the user request, lists files, and coordinates.
• Planner Agent (Brain): Pure LLM-only agent. Has no filesystem access. It receives the code and generates high-level plans or precise refactoring edits.
• Coder Agent (hands): Tools-only agent (no LLM). It executes deterministic operations like reading/writing files and searching directories.

The Orchestrator coordinates them using standard A2A delegation modes: calling the Coder with tool_call parts, and calling the Planner with infer parts. The code stays clean because the concerns are completely separated.

2. Deep Composition (Pipeline -> Parallel -> Pipeline)

Because all flows are polymorphic and recursively nestable, you can nest parallel committees inside a pipeline:

pythonfrom protolink.flows import Pipeline, Parallel
from protolink.agents import Agent
from protolink.models import Task
# 1. Spin up some agents
researcher = Agent(card={"name": "researcher", "url": "http://localhost:8081"}, ...)
sec_inspector = Agent(card={"name": "security_inspector", "url": "http://localhost:8082"}, ...)
fmt_inspector = Agent(card={"name": "format_inspector", "url": "http://localhost:8083"}, ...)
summarizer = Agent(card={"name": "summarizer", "url": "http://localhost:8084"}, ...)
# 2. Build a Parallel Flow representing a review committee
review_committee = Parallel(
    branches=["security_inspector", "format_inspector"], 
    registry=registry
)
# 3. Nest the Parallel block as a step inside a Parent Pipeline
orchestrated_flow = Pipeline(registry=registry) \
    .add_step(researcher) \
    .add_step(review_committee) \
    .add_step(summarizer)
# 4. Execute standard A2A task
task = Task.create_infer(prompt="Audit and summarize the codebase's WebSocket implementation.")
result = await orchestrated_flow.execute(task)

I'd Love Your Feedback !

I wanted to build an agent framework that acts like a predictable, observable distributed system rather than a black box.

I'd love to hear your thoughts:

• Does this align with how you see A2A scale in production?
• How would you balance structured state-machine flow control with agent autonomy in your projects?
• What are your thoughts on Semantic Context Injection vs. hardcoded agent interactions?
• How would you manage human-in-the-loop safety approvals and cooperative cancellation in your own architectures?

Check it out here: https://github.com/nMaroulis/protolink And the docs: https://nmaroulis.github.io/protolink/ and a medium post on Level-Up-Code: https://levelup.gitconnected.com/build-easily-your-own-claude-code-with-three-agents-brain-hands-and-coordinator-5236b392ddf0

Let me know what you think!