postbridge-langchain 0.1.0

PostBridge postal tools for LangChain and LangGraph — send physical letters to 5 countries from any LangChain agent.

postbridge-langchain

Drop-in PostBridge tools for LangChain and LangGraph — send physical letters to US, France, UK, Canada, and Germany from any LangChain agent, chain, or LangGraph node.

Install

# Core — tools + args validation only
pip install postbridge-langchain

# With AgentExecutor + OpenAI chat support
pip install "postbridge-langchain[agents]"

# With LangGraph
pip install "postbridge-langchain[langgraph]"

Quickstart — llm.bind_tools()

from langchain_openai import ChatOpenAI
from postbridge_langchain import postbridge_tools

llm = ChatOpenAI(model="gpt-4o-mini")
tools = postbridge_tools()                       # all 8 tools
llm_with_tools = llm.bind_tools(tools)

response = llm_with_tools.invoke("Send a letter to Paris saying hello")
# response.tool_calls → [{"name": "send_letter", "args": {...}}, ...]

Quickstart — LangChain 1.x create_agent

from langchain.agents import create_agent
from langchain_openai import ChatOpenAI
from postbridge_langchain import postbridge_tools

agent = create_agent(
    model=ChatOpenAI(model="gpt-4o-mini"),
    tools=postbridge_tools(),
    system_prompt="You are a postal assistant. Use tools to send letters.",
)

result = agent.invoke({"messages": [("human", "Send a letter to Paris saying hello")]})
print(result["messages"][-1].content)

Quickstart — LangChain 0.3.x (AgentExecutor, legacy)

from langchain.agents import AgentExecutor, create_tool_calling_agent
from langchain_core.prompts import ChatPromptTemplate
from langchain_openai import ChatOpenAI
from postbridge_langchain import postbridge_tools

llm = ChatOpenAI(model="gpt-4o-mini")
tools = postbridge_tools()
prompt = ChatPromptTemplate.from_messages([
    ("system", "You are a postal assistant..."),
    ("human", "{input}"),
    ("placeholder", "{agent_scratchpad}"),
])
agent = create_tool_calling_agent(llm, tools, prompt)
executor = AgentExecutor(agent=agent, tools=tools, verbose=True)
result = executor.invoke({"input": "Send a letter to Paris..."})

Quickstart — LangGraph

from langchain_openai import ChatOpenAI
from langgraph.prebuilt import create_react_agent
from postbridge_langchain import postbridge_tools

llm = ChatOpenAI(model="gpt-4o-mini")
graph = create_react_agent(llm, tools=postbridge_tools())

result = graph.invoke({"messages": [("human", "Send a letter to Paris saying hello")]})

Tools available

Tool	HTTP	Purpose
list_services	GET /api/services/{country}	Discover services per country
quote_letter	POST /api/quote	Price a letter
send_letter	POST /api/send	Mail it
track_letter	GET /api/track/{letter_id}	Live status
get_proof	GET /api/proof/{letter_id}	Signed PostalProof VC
get_balance	GET /api/balance	Wallet + ledger
negotiate_pricing	POST /api/anp/offer	ANP tiered offer
accept_offer	POST /api/anp/accept	Lock in tier

Subset selection

# Read-only agent
tools = postbridge_tools(only=["list_services", "quote_letter", "track_letter", "get_proof"])

# Send-only dispatcher
tools = postbridge_tools(only=["send_letter", "track_letter"])

# Full ANP flow
tools = postbridge_tools(only=["negotiate_pricing", "accept_offer", "send_letter"])

Async support

Every tool implements both _run (sync) and _arun (async), so LangGraph's async nodes and LangChain's ainvoke work out of the box:

result = await llm_with_tools.ainvoke("Quote a letter to Berlin")

Authentication

Tools call https://api.postbridge.ai and read POSTBRIDGE_API_KEY from the environment. Three ways to get a key:

1. Auto-provision (no signup):

curl -X POST https://api.postbridge.ai/auth/agent \
  -H 'Content-Type: application/json' \
  -d '{"agent_id": "my-agent", "agent_name": "My LangChain Agent"}'

2. Register with email: postbridge.ai/developers.html

3. Pay-per-request with x402 USDC (no API key needed): see postbridge.ai.

How it works

Every tool is a langchain_core.tools.BaseTool subclass generated from the shared tools.json catalog that also powers PostBridge's OpenAI / Anthropic / Gemini / Mistral adapters. JSON Schema → Pydantic args_schema conversion catches bad inputs before they hit the API.

Tool execution delegates to the shared dispatcher.execute() — one HTTP path for all provider integrations, with path-param resolution, auth injection, and error surfacing.

Design rules (enforced by the API)

• Rate-table pricing — no LLM-estimated prices
• API-validated addresses — no LLM-composed addresses
• Recipient-country routing — postal service matches the destination
• Digital-only proof — certified-mail receipts are webhook/API/email
• Pricing confidentiality — internal pricing fields scrubbed from every response

Related

• Main API docs: postbridge.ai/developers.html
• Agent metadata: postbridge.ai/.well-known/agent.json
• Source of truth catalog: integrations/schemas/tools.json
• Sister packages: postbridge-crewai (CrewAI), adapters for OpenAI / Anthropic / Gemini / Mistral
• Example agent: examples/langchain_sendletter.py