← articles

Architecting Agentic Systems: Lessons from Building Lineage MCP and MergeOracle

Discover how to build secure, context-aware AI systems. In this deep dive, I share my journey architecting the Lineage MCP server for blockchain execution and orchestrating multi-agent workflows with Google ADK to build MergeOracle—tackling precision errors, observability, and agent hallucinations along the way.

Architecting Agentic Systems: Lessons from Building Lineage MCP and MergeOracle

What Is Google ADK?

Google ADK is an open-source framework that simplifies creating, deploying, and managing autonomous agents. Built on top of the Gemini API, it abstracts away the heavy lifting of agent orchestration so developers can focus on building intelligent logic rather than boilerplate infrastructure.

What is a MCP Server?

The Model Context Protocol (MCP) is an open standard that enables developers to build secure, two-way connections between data sources and AI-powered tools. It's like USB for AI: it defines how an AI can seamlessly plug into your data and services.

Experience Building An MCP Server

I took an interest in understanding the AI landscape and tools during my research on a project called Lineage MCP. The objective was to build an MCP server that AI agents could use to query and transact on the Lineage Protocol.

Once I dug into the core concepts, it clicked. With my backend engineering experience, the learning curve was surprisingly gentle. Building an MCP server is exactly like building a standard backend API—except your end-user is an AI agent, not a human.

I architected the Lineage MCP server as a robust three-layer stack:

  1. The AI Strategist (The Brain): Agents built with Google ADK communicating via standard MCP HTTP-SSE.
  2. The MCP Gateway (The Hands): A Python FastMCP server handling non-custodial local signing.
  3. The Valence Gateway (The Network): A high-performance broadcasting layer for transaction propagation.

When building for financial operations, standard API rules don't apply. I had to implement a strict "Decimal-First" rule to prevent IEEE 754 floating-point errors (because 0.1 + 0.2 needs to exactly equal 0.3, not 0.30000000000000004). Every tool input is processed as a precise Decimal string, and the server runs an automated pre-flight total_cost = amount + estimate_fee check against the live balance before allowing the agent to generate a signature.

Furthermore, debugging agent decisions requires rigorous enterprise observability. If an agent "hallucinates" a transaction, you need a forensic trail. To solve this, I built a recursive log-filter that auto-redacts sensitive PII (like private keys and passphrases) while injecting a unique UUID Correlation ID into every request.

To visualize this, here is the lifecycle of a transaction passing through the stack:

sequenceDiagram
    participant Agent as ADK Strategist (10000)
    participant MCP as Lineage MCP Server (8000)
    participant SDK as Lineage SDK (Internal)
    participant Valence as Valence Gateway (External)

    Note over Agent, Valence: Step 1: Request & Context
    Agent->>MCP: POST /mcp (get-balance)
    MCP-->>Agent: JSON (Balance: 100.0)

    Note over Agent, Valence: Step 2: Intent Formulation
    Agent->>MCP: POST /mcp (transfer-funds {amount: 10})

    Note over Agent, Valence: Step 3: Precision & Fee Validation
    MCP->>SDK: Estimate Fee
    SDK-->>MCP: 0.0011 Tokens
    alt Balance >= 10.0011
        MCP->>SDK: Sign Intent with Local Key
        SDK-->>MCP: Signed Transaction String
    else Insufficient Funds
        MCP-->>Agent: Error (Insufficient Funds)
    end

    Note over Agent, Valence: Step 4: Broadcast
    MCP->>Valence: POST /v1/broadcast (Signed Intent)
    Valence-->>MCP: 202 Accepted (TX ID: 0xabc...)
    MCP-->>Agent: Success (TX ID: 0xabc...)

Orchestrating Agents with Google ADK

I had been hearing a lot about agents, the kind of tools people were building, and the capabilities they brought to the table. As a developer who loves building systems, I knew I had to try it out for myself. I came across Google ADK, and to be sincere, I have always been a big fan of Google. The promise of a smooth experience building agents in Go was something I could not resist.

I began studying Google ADK from its official documentation and GitHub repository. I read the code, learned the best practices, and built sample projects to get a hands-on feel for the framework.

It was a cycle of figuring out what I wanted to build, testing if it could be done with ADK and LLMs, learning from AI chats, applying the knowledge, failing, debugging, and repeating.

After a few days of building simple test agents, I moved on to a more sophisticated system that could orchestrate multiple agents sequentially to perform complex tasks.

I built MergeOracle, an agentic CLI tool for developers that helps eliminate the overhead of understanding complex GitHub issues and PRs. Instead of reading through 50+ comments to find the root cause, MergeOracle does it for you in seconds.

The agents in MergeOracle orchestrate themselves to perform specific, deep-dive tasks such as:

  • Fetching and parsing repository metadata from GitHub.
  • Formatting system context to include language-specific data.
  • Analyzing issue threads with context-aware insights.
  • Generating reports with stack-specific suggestions.

Building this agentic system was especially interesting because I got to understand what multi-agent systems, agent orchestration, and Retrieval-Augmented Generation (RAG) really mean in practice.

Interesting Challenges I Faced

Were there problems encountered? Absolutely. One major hurdle was making the CLI experience seamless. I didn't want developers dealing with the clunky User -> Agent chat loop typical of CLI bots. I wanted a fast, native feel. This immediately brought up session and memory management challenges.

Instead of relying on generic session IDs, I engineered a dynamic session identifier using unique identifier and the local user environment. This gave the agent persistent context without requiring the developer to manually manage sessions.

Then came the agent hallucinations. Early on, the agent would analyze a Go repository and suggest a solution using Rust paradigms—it was a mess. To fix this, I didn't just use standard RAG; I implemented strict context-awareness. I enriched the GitHub Issue payload with repository metadata and anchored the agent's prompts (specifically my analyzer and responder prompts) tightly to the System Context. By explicitly enforcing stack-specific rules, the agent stopped mincing languages and started acting like a senior engineer reviewing code in the correct stack.

Every challenge was a thrilling experience, to say the least, and I enjoyed every bit of it.

Conclusion

Building an MCP server and orchestrating agents with Google ADK was a fun and highly educational experience. It helped me understand what it truly takes to build a robust agent system, the common pitfalls to avoid, the importance of strict prompt engineering and RAG, and how to build a system that developers can actually use to improve their workflow.

This project opened my eyes to the future of AI and how it can be used to solve real-world problems efficiently and effectively.

I would recommend it to anyone looking to get started with building agentic systems or just looking to get a hands-on feel for the framework. If you want to contribute to an ongoing agentic project to understand orchestration better, check out MergeOracle.

Resources

Comments
← back to articles