Local Agent API — LangGraph, OpenClaw & Self-Hosted Agent Loops

A local agent architecture does not require local inference. Run LangGraph, LangChain, or OpenClaw on your workstation, VM, container platform, or private network, then send only model requests through LumeAPI. Your agent process keeps ownership of tool execution, state, secrets, retrieval indexes, shell access, and approval workflows. LumeAPI provides the OpenAI-compatible Chat Completions endpoint the agent uses for text generation.

Point OpenAI-compatible clients at https://api.lumeapi.site/v1 and authenticate with a Bearer API key from the LumeAPI Console. The base URL must stop at /v1. Do not append /chat/completions in LangChain, LangGraph, OpenClaw, or SDK client configuration; those clients construct the Chat Completions path themselves.

The practical advantage is per-hop routing. A graph does not need to use one expensive model from intake through final answer. Use gemini-3-flash for classification and lightweight extraction, gpt-5.4-mini for plans and tool selection, claude-sonnet-4-6 for synthesis, and gpt-5.6-sol only when the task has earned escalation. This makes model choice an explicit part of graph design instead of a global application setting.

LumeAPI is an independent service. It is not OpenAI, Anthropic, or Google.

Use stable catalog IDs in graph nodes and routing rules. The rates below are LumeAPI catalog input/output prices as updated 2026-07-22.

Rates are catalog figures, not a promise about the total cost of an agent run. Tool calls, retries, long prompts, retrieved context, and output limits still determine spend.

LangGraph supports separate model instances per node. Treat that as a production control: each node should have an assigned task, model, output contract, timeout policy, and escalation condition.

• 1. Create a LumeAPI API key in the Console and store it in the runtime secret manager rather than in graph source code.
• 2. Set OPENAI_API_KEY to that key and set OPENAI_BASE_URL to https://api.lumeapi.site/v1 in the process environment.
• 3. Create separate ChatOpenAI instances for gemini-3-flash, gpt-5.4-mini, claude-sonnet-4-6, and gpt-5.6-sol. Set base_url to https://api.lumeapi.site/v1 on every instance when you need explicit configuration.
• 4. Put classification in its own LangGraph node and require a structured result such as route, confidence, risk level, and retrieval_required. Keep this node on gemini-3-flash.
• 5. Put planning in a separate node using gpt-5.4-mini. Have it produce a bounded tool plan with an allowed tool list, arguments, and a stop condition.
• 6. Run tools in dedicated nodes owned by your application. Do not give the model unrestricted shell, database, or network access simply because the graph is local.
• 7. Send retrieved documents and verified tool outputs to a synthesis node using claude-sonnet-4-6. Include source identifiers in state so the node can cite what it actually received.
• 8. Add an explicit conditional edge to gpt-5.6-sol only for defined triggers: failed plan validation, conflicting evidence, repeated tool errors, or a high-impact request class.
• 9. Apply a per-node recursion or retry budget. A failed tool loop should terminate with diagnostic state, not silently burn tokens through repeated planning.
• 10. Log graph node name, model ID, input token estimate, output token estimate, route decision, and terminal status. Redact API keys and sensitive tool payloads before logs leave the runtime.

For LangGraph's prebuilt agent flow, the relevant construction pattern is create_react_agent(llm, tools). For custom graphs, instantiate a different LLM per node rather than mutating one shared client.

import os
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent

# Export these before running:
# export OPENAI_API_KEY='YOUR_LUMEAPI_KEY'
# export OPENAI_BASE_URL='https://api.lumeapi.site/v1'

BASE_URL = os.environ.get("OPENAI_BASE_URL", "https://api.lumeapi.site/v1")
API_KEY = os.environ["OPENAI_API_KEY"]

classifier_llm = ChatOpenAI(
    model="gemini-3-flash",
    api_key=API_KEY,
    base_url=BASE_URL,
    temperature=0,
)
planner_llm = ChatOpenAI(
    model="gpt-5.4-mini",
    api_key=API_KEY,
    base_url=BASE_URL,
    temperature=0,
)
synthesis_llm = ChatOpenAI(
    model="claude-sonnet-4-6",
    api_key=API_KEY,
    base_url=BASE_URL,
    temperature=0.2,
)
escalation_llm = ChatOpenAI(
    model="gpt-5.6-sol",
    api_key=API_KEY,
    base_url=BASE_URL,
    temperature=0,
)

@tool
def get_order_status(order_id: str) -> str:
    """Return a verified order status for an order ID."""
    # Replace with an authenticated call to your internal service.
    return f"Order {order_id}: status unavailable in this example."

# A tool-using node can have its own model assignment.
planner_agent = create_react_agent(planner_llm, [get_order_status])

# In a custom StateGraph, call classifier_llm in the routing node,
# invoke planner_agent in the planning/tool node, call synthesis_llm
# in the response node, and reserve escalation_llm for conditional edges.

result = classifier_llm.invoke(
    "Classify this request as simple, tool_required, or escalation: "
    "Where is order A-1042?"
)
print(result.content)

Do not change BASE_URL to https://api.lumeapi.site/v1/chat/completions. ChatOpenAI adds the Chat Completions path.

OpenClaw custom providers should use a new provider name. Do not attempt to override the built-in openai provider base URL.

• 1. Open the OpenClaw configuration file used by the agent runtime and locate the models.providers configuration path.
• 2. Add a new custom provider under models.providers named lumeapi. Do not modify the built-in openai provider entry.
• 3. Set models.providers.lumeapi.baseUrl to https://api.lumeapi.site/v1 exactly. Do not add /chat/completions.
• 4. Set models.providers.lumeapi.api to openai-completions so OpenClaw uses the OpenAI-compatible Chat Completions interface.
• 5. Supply the LumeAPI key at models.providers.lumeapi.apiKey using your deployment's secret-injection mechanism. Avoid committing the key in shared configuration.
• 6. Add the model IDs your workflows use under models.providers.lumeapi.models, including gemini-3-flash, gpt-5.4-mini, claude-sonnet-4-6, and gpt-5.6-sol.
• 7. Set the provider configuration mode to merge so the custom provider is added without replacing unrelated configured providers.
• 8. Set agents.defaults.model.primary to lumeapi/gpt-5.4-mini for a sensible default planning model, then assign other LumeAPI models in agents that need different roles.
• 9. Restart or reload the OpenClaw runtime using its normal deployment procedure, then send a small prompt that confirms the selected model ID in application logs.
• 10. Test a tool-enabled agent separately from a plain chat agent. Provider connectivity does not prove that your tool permission policy, tool schemas, or approval gates are correct.

The relevant OpenClaw settings paths are models.providers, models.providers.lumeapi.baseUrl, models.providers.lumeapi.api, models.providers.lumeapi.apiKey, models.providers.lumeapi.models, and agents.defaults.model.primary.

The most common routing mistake is sending every message to the strongest available model because the first demo looked better. That approach hides cost in routine traffic: greetings, basic extraction, duplicate tickets, simple status questions, and requests that should have been answered by a tool call. A local agent can make cheaper decisions before it spends on synthesis.

Start with a routing contract. The classifier returns a narrow label, the planner can request only approved tools, and the synthesis node receives evidence rather than raw access to every system. Escalation should depend on visible state: low classifier confidence, validation failure, conflicting tool results, policy-sensitive categories, or a capped number of unsuccessful attempts. Do not escalate merely because a model generated a long answer.

Track spend by graph node and route, not only by user session. If claude-sonnet-4-6 synthesis dominates cost, reduce duplicate context and cap outputs before changing models. If gpt-5.6-sol appears frequently, inspect the reason codes. A high escalation rate usually indicates an unclear router, weak tool result schemas, missing retrieval filters, or a task that needs a human-owned workflow rather than a larger model.

Input and output rates differ substantially for several models. Output limits are a direct routing and cost control, especially for planning and synthesis nodes.

Local deployment changes where your agent runs, not the need for controls around credentials, tool authority, retries, and observability.

• 1. Inject the LumeAPI key at runtime and rotate it through the same process used for other production secrets. Confirm that OPENAI_API_KEY never appears in traces, exception text, or support bundles.
• 2. Allow outbound access only to https://api.lumeapi.site/v1 where your network policy supports domain-based egress rules. Keep internal tools on their existing private network boundaries.
• 3. Set explicit maximum output sizes for each node. Classifiers should return compact labels; planners should return bounded action lists; synthesis should have a user-visible response limit.
• 4. Validate model output before it controls an edge or tool invocation. Parse route labels, tool arguments, identifiers, and policy flags against application-defined schemas.
• 5. Use idempotency-aware tool design. A graph retry must not accidentally create duplicate tickets, issue duplicate refunds, or repeat state-changing operations.
• 6. Separate read-only and write-capable tools. Require an approval node, a user confirmation, or a service-side policy check before write-capable operations run.
• 7. Add timeouts and a finite retry count around both model calls and tools. Preserve the failed node, route reason, and safe error summary in graph state for debugging.
• 8. Build a replay set of representative requests: simple requests, tool-required requests, ambiguous requests, unsafe requests, and known failure cases. Run it whenever prompts, model routing, or tool schemas change.
• 9. Monitor model ID distribution, escalation percentage, tool error rate, retry count, and completion length. Alert on route shifts that could indicate a broken classifier or an unexpected workload change.
• 10. Document client limitations before standardizing developer tools. For example, Cursor tab completion may not use a custom URL even when a chat-oriented integration supports OpenAI-compatible endpoints.

OpenAI compatibility applies to text-model Chat Completions usage. Validate each local agent feature independently instead of assuming every editor, completion mode, or provider-specific capability accepts a custom endpoint.