postbridge-crewai 0.1.0

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

postbridge-crewai

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

Install

pip install postbridge-crewai
# Or from the monorepo:
pip install -e integrations/postbridge_crewai

Quickstart

from crewai import Agent, Crew, Task, Process
from postbridge_crewai import postbridge_tools

postal_clerk = Agent(
    role="Postal Clerk",
    goal="Send physical letters via PostBridge",
    tools=postbridge_tools(),        # all 8 tools
    verbose=True,
)

task = Task(
    description="Send a letter to Marie Dupont, 15 Rue de Rivoli, 75001 Paris...",
    expected_output="Confirmation with letter_id, price, and status.",
    agent=postal_clerk,
)

crew = Crew(agents=[postal_clerk], tasks=[task], process=Process.sequential)
result = crew.kickoff()

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

Most crews don't need every tool. Filter:

# Read-only reporter
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 negotiation crew
tools = postbridge_tools(only=["negotiate_pricing", "accept_offer", "send_letter"])

Authentication

The 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-crew", "agent_name": "My CrewAI Crew"}'

Response includes api_key. Export it:

export POSTBRIDGE_API_KEY=pb_live_...

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

3. Pay-per-request with x402 USDC: skip auth entirely, pay from an EVM wallet (Base L2) per call. See postbridge.ai for x402 setup.

How it works

Under the hood, every tool is a BaseTool subclass generated from the shared tools.json catalog that also powers PostBridge's OpenAI / Anthropic / Gemini / Mistral adapters. The catalog's JSON Schema is converted into a Pydantic args_schema so CrewAI's built-in validation 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

The tools enforce PostBridge's determinism rules automatically because validation and routing happen server-side:

• Rate-table pricing — no LLM-estimated prices
• API-validated addresses — no LLM-composed addresses
• Recipient-country routing — postal service matches the destination, never the sender
• Digital-only proof — certified-mail receipts are webhook/API/email (never physical)
• 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
• Other adapters: OpenAI, Anthropic, Gemini, Mistral under integrations/schemas/
• Example crew: examples/crewai_sendletter.py