LangGraph Tool Execution: LangChain vs External Agent Harness — Trade Space

Status: ACTIVE (conversation observation) Agent: opencode/ext-agent (sandshrew) Timestamp UTC: 2026-05-11T18:55:00Z Claim: synthesis | 2026-05-11T18:50:00Z Session: MjF trade-off exploration — LangChain tools vs Pi/Hermes agents inside LangGraph nodes

Prior Context

• [[langgraph-node-anatomy]] — Full node anatomy catalog
• [[langgraph-game-surface]] — Game backend architecture
• Pearl Brain: research-sandshrew-20260511-180853 — Tool calls without LangChain
• This page: trade-off profile between LangChain tool integration and external agent harnesses

The Core Tension (As Observed)

Two paths for tool execution inside LangGraph nodes:

What LangGraph Actually Cares About

LangGraph is an orchestration runtime. It cares about three things: 1. State — what keys exist and how updates merge 2. Nodes — functions that receive state and return updates 3. Edges — how the next node is chosen

LangGraph does NOT care how a node produces its update. The official docs state: "You don't need to use LangChain to use LangGraph." Nodes are plain Python functions. Inside a node, the developer can call an LLM directly, invoke a LangChain tool, shell out to a Bun process, make an HTTP request to a Pi agent, or run pure Python logic. LangGraph is indifferent.

This means LangChain tools are NOT the native convention — they are ONE option among many. The node's internal implementation is LangGraph's blind spot by design.

Observed Boundary: What Granularity of State Tracking Is Needed?

The choice hinges on how much of the tool execution pipeline needs to be visible in LangGraph state:

Observed Patterns for Bridging

Pattern A: Black Box

def hex_node(state: State):
    """LangGraph owns routing + state. Agent handles everything inside."""
    agent = get_agent("hermes")
    result = agent.run(
        task="Unit at hex_17 with enemies nearby. Decide and act.",
        context={"state": state, "unit": state["unit"]}
    )
    return {"last_action": result.action, "unit": result.updated_state}

LangGraph asks "what should we do here?" The agent answers. LangGraph tracks the outcome, not the process. LangGraph state only sees: input → agent decision → output. Intermediate tool calls (the agent deciding to scout, then move, then attack) are invisible to LangGraph — they're the agent's internal reasoning loop.

Pattern B: Full Visibility

# Each tool is a LangChain tool, each call is a state checkpoint
graph.add_node("hex_node", ToolNode([
    move_tool, attack_tool, scout_tool, use_item_tool
]))

LangGraph sees every tool invocation. State tracks: unit requested move, state updated with new position, next tool scout fires. Every step is checkpointable and interruptible. But every tool must be in the schema at compile time.

Pattern C: Hybrid — LangGraph Routes, Agent Decides

def hex_node(state: State, runtime: Runtime):
    """LangGraph provides situation. Agent decides which tools to use.
    Agent reports back high-level outcomes. LangGraph tracks those."""

    # LangGraph sends structured situation to agent
    situation = {
        "turn": state["turn"],
        "unit": state["unit"],
        "nearby": state["nearby_units"],
        "terrain": state["terrain"][state["unit"]["position"]],
        "objectives": state["objectives"],
        "available_tools": ["move", "attack", "scout", "fortify"]
    }

    # Agent (Pi/Hermes) decides internally, uses its own tools
    agent = runtime.context.get_agent("pi")
    decision = agent.decide(situation)

    # LangGraph tracks the decision at a high level
    return {
        "unit_action": decision.action,       # "attack hex_18"
        "unit_target": decision.target,
        "action_log": decision.reasoning,      # agent's internal reasoning, logged
        "unit_state": decision.unit_update     # health deltas, position, etc.
    }

LangGraph owns the graph topology, state schema, routing, and checkpoints. The agent owns tool selection and execution. The interface is a structured handoff: "here's the situation and available tools" → "here's what I decided and what changed." LangGraph never needs to know whether the agent called scout before attack — it only needs the outcome.

This avoids both problems: - No pre-staging every tool in LangChain format - No fighting LangGraph's routing — routing remains LangGraph's job - Agent adaptivity is preserved — it can chain tools or invent new approaches

Observed: Runtime Separation Concern

Pi agents run on Bun (JavaScript). LangGraph runs on Python. If both run on the same Pi:

Same-machine options: - LangGraph Python node → subprocess call to Bun → Pi agent runs → returns JSON → LangGraph resumes - LangGraph Python node → HTTP call to local Pi agent server → JSON response - LangGraph threads and Pi agent as separate OS processes, state passed via JSON

Cross-machine options: - LangGraph on Pi, Pi agent HTTP server on Pi → simplest - LangGraph on Mac, Pi agent on Pi → network calls, need Tailscale or LAN

The subprocess pattern (Python calling Bun) is the tightest coupling but also the least overhead. The HTTP pattern is cleaner separation but adds a local server that must stay running.

Open Questions (Not Prescriptive)

• Is the tool visibility trade-off real in practice, or does Pattern C (high-level outcome tracking) cover enough ground for a game surface?
• How much does the Bun→Python subprocess overhead actually cost on a Pi 4 per turn?
• Could Pi agents be configured to expose their internal tool calls as streamed events that LangGraph could optionally subscribe to, without making them mandatory state keys?
• If the game surface evolves to need mid-tool-execution interrupts (e.g., "scout found something — stop and let human decide"), does that force a move toward Pattern B?