postbridge-llamaindex 0.1.0

PostBridge postal tools for LlamaIndex — send physical letters to 5 countries from any LlamaIndex agent.

postbridge-llamaindex

Drop-in PostBridge tools for LlamaIndex — send physical letters to US, France, UK, Canada, and Germany from any LlamaIndex agent.

Install

pip install postbridge-llamaindex
# Or from the monorepo:
pip install -e integrations/postbridge_llamaindex

Quickstart — FunctionAgent (function calling)

import asyncio
from llama_index.llms.openai import OpenAI
from llama_index.core.agent.workflow import FunctionAgent
from postbridge_llamaindex import postbridge_tools

agent = FunctionAgent(
    tools=postbridge_tools(),        # all 8 tools
    llm=OpenAI(model="gpt-4o-mini"),
    system_prompt="You are a postal assistant...",
)

response = asyncio.run(agent.run(
    "Send a letter to Marie Dupont at 15 Rue de Rivoli, 75001 Paris, France..."
))
print(response)

Quickstart — ReActAgent (works with any LLM)

from llama_index.core.agent import ReActAgent
from llama_index.llms.openai import OpenAI
from postbridge_llamaindex import postbridge_tools

agent = ReActAgent.from_tools(
    tools=postbridge_tools(),
    llm=OpenAI(model="gpt-4o-mini"),
    verbose=True,
)

response = agent.chat("Send a letter to Paris...")

Quickstart — Direct tool binding

from llama_index.llms.openai import OpenAI
from postbridge_llamaindex import postbridge_tools

llm = OpenAI(model="gpt-4o-mini")
result = llm.predict_and_call(
    tools=postbridge_tools(only=["quote_letter"]),
    user_msg="What would it cost to send a letter to 75001 Paris via fr_lettre_verte?",
)
print(result)

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

Filter the toolkit to match your agent's scope:

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

# Dispatcher agent — send + track
tools = postbridge_tools(only=["send_letter", "track_letter"])

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

Authentication

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

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 LlamaIndex Agent"}'
export POSTBRIDGE_API_KEY=pb_live_...

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

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

Async support

Every tool ships with both a sync and async path. LlamaIndex's modern agent flows (FunctionAgent, AgentWorkflow) use the async variant by default. The async wrapper runs the HTTP call in a worker thread so it doesn't block the event loop.

How it works

Tools are dynamically generated from PostBridge's canonical tools.json catalog — the same source that powers the OpenAI / Anthropic / Gemini / Mistral / CrewAI / LangChain adapters. Each LlamaIndex FunctionTool gets:

• fn_schema — Pydantic model built from the tool's JSON Schema (includes enums, optionals, descriptions)
• fn + async_fn — both routes delegate to the shared dispatcher.execute()

One source of truth, consistent validation across every agent framework PostBridge supports.

Design rules

The tools enforce PostBridge's server-side determinism:

• 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 via webhook/API/email
• Pricing confidentiality — internal pricing fields scrubbed from responses

Related

• Main API docs: postbridge.ai/developers.html
• Agent metadata: postbridge.ai/.well-known/agent.json
• Source catalog: integrations/schemas/tools.json
• Example: examples/llamaindex_sendletter.py
• Other adapters: postbridge-crewai, postbridge-langchain (same monorepo)