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

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