LangGraph agent cost tracking: cost per node, per run, and a hard budget per agent run

LangGraph agents make many model calls per user request, often in loops whose length depends on the model's own decisions. That makes two numbers matter: what each node costs, and what one run costs. The gateway gives you both without instrumenting the graph.

One model per node, one run ID per invocation

import uuid
from langchain_openai import ChatOpenAI
 
GATEWAY = dict(api_key="sk-cog-YOUR-KEY", base_url="https://api.cognocient.com/v1")
 
def models_for_run(run_id: str, budget_usd: str = "1.00"):
    run = {"X-Cost-Run-ID": run_id, "X-Cost-Run-Budget": budget_usd}
    return {
        "planner": ChatOpenAI(model="claude-sonnet-4-6", **GATEWAY,
                              default_headers={"X-Cost-Feature": "research-agent:planner", **run}),
        "worker":  ChatOpenAI(model="gpt-4o-mini", **GATEWAY,
                              default_headers={"X-Cost-Feature": "research-agent:worker", **run}),
    }
 
run_id = str(uuid.uuid4())
models = models_for_run(run_id)
# build your StateGraph with models["planner"] and models["worker"] in the node functions,
# then: graph.invoke(inputs, config={"recursion_limit": 25})

Chat model objects are cheap to construct, so creating them per invocation is fine. Each node's spend appears as its own feature on every plan. Grouping a run's calls in Sessions needs Growth; the Agent Workflows tree needs Business.

Prebuilt agents

from langchain.agents import create_agent   # LangChain 1.x; older code: langgraph.prebuilt.create_react_agent
 
agent = create_agent(model=models["planner"], tools=[search, fetch_page])
agent.invoke({"messages": [{"role": "user", "content": "Compare three vendors."}]})

Tool calls with Claude through ChatOpenAI work streamed or not; the gateway translates tools and tool_choice both ways.

Steps are not dollars

recursion_limit stops a graph after N steps, but one step on a frontier model with a 100k-token context can cost more than fifty small ones. X-Cost-Run-Budget is a dollar ceiling for the whole run, reserved atomically before each call, so parallel branches can't jointly overshoot it. When it is reached the next model call fails with 429 and type: run_budget_exceeded, which LangGraph surfaces as an exception you can catch and turn into a graceful answer.

MCP tools and sub-agents

If nodes call MCP servers or hand off to sub-agents, add X-Cost-MCP-Server, X-Cost-Parent-Run-Id and X-Cost-Agent-Handoff to build a full cost tree (Business plan). See MCP / A2A attribution.