Agent Broker

@basilalshukaili

Visit Server

a month ago

# booking

MCP server for AI agents to interact with SMBs — book appointments, send messages, find businesses. 13 tools. Compliance pre-check (TCPA, GDPR, CASL). Channel fallback: Cal.com → voice → SMS → email → web form.

Overview Tools Comments

Overview

SMB Transaction & Communication Broker

An agent-callable service that lets autonomous AI agents discover, verify, communicate with, schedule with, and transact with the long tail of small and mid-sized businesses (SMBs) — through a single compliance-aware tool surface.

👁 Tests
👁 License
👁 Python
👁 Edge

Why this exists

There are ~60 million long-tail small businesses in the US — barbers, plumbers, accountants, home cleaners — and they have no API surface. AI agents that need to schedule a haircut, get a quote on a roof repair, or send a transactional confirmation today have to either: (a) drive a browser, (b) cold-call by voice, or (c) give up.

This service is the missing layer. Agents call us; we route to the right SMB through whichever channel reaches them fastest — Cal.com → SMS → voice AI → email → web form fallback — with full TCPA / GDPR / CASL / 10DLC / two-party recording-consent compliance enforced as a non-bypassable gate.

What you can do with it

13 operations, all callable via REST, MCP, OpenAI tools, Anthropic tools, or A2A protocol:

Operation	What it does	Cost	Latency
`find_business`	Search SMBs by vertical + location + capability	$0.01	<2s
`verify_business`	Confirm an SMB has the capability you need	$0.01	<2s
`send_message`	SMS / email / voice with full compliance pre-check	$0.05	<5s
`capture_lead`	Hand a prospect to an SMB with dedup	$0.02	<2s
`schedule_appointment`	Book / reschedule / cancel — direct API → voice fallback	$0.15 base + $0.85 success premium	<5s sync, async otherwise
`send_transactional_confirmation`	TCPA-exempt confirmations (booking, receipt)	$0.04	<5s
`handle_inbound`	Classify customer messages (booking / cancel / opt-out / question)	$0.03	<5s
`escalate_to_human`	Hand off to a human when an agent is stuck	$0.10 base + $0.40 success premium	async
`get_status`	Poll status of an async operation	$0.001	<1s
`get_outcome`	Retrieve final outcome of an async operation	$0.001	<1s
`preview_cost`	Estimate cost / latency / success probability — free	$0.00	<500ms
`self_test`	Service health check — free	$0.00	<2s
`import_booking_url`	Parse any Cal.com / Calendly / Doctolib / Booksy / OpenTable / 7 more URLs into a bookable SMB	$0.01	<2s

Quick start (for AI agents)

Option 1: MCP (Claude Desktop, Cursor, Continue, etc.)

// Add to your MCP client config
{
 "mcpServers": {
 "agent-broker": {
 "url": "https://agent-broker-edge.basil-agent.workers.dev/mcp",
 "headers": { "X-Agent-Identity": "$AGENT_BROKER_TOKEN" }
 }
 }
}

Option 2: OpenAI function calling

import httpx, openai
tools = httpx.get("https://agent-broker-edge.basil-agent.workers.dev/.well-known/openai-tools.json").json()["tools"]
client = openai.OpenAI()
resp = client.chat.completions.create(
 model="gpt-4",
 messages=[{"role":"user","content":"Book me a haircut in Atlanta for Saturday under $50"}],
 tools=tools,
)

Option 3: Anthropic tool use

import httpx, anthropic
tools = httpx.get("https://agent-broker-edge.basil-agent.workers.dev/.well-known/anthropic-tools.json").json()["tools"]
client = anthropic.Anthropic()
msg = client.messages.create(
 model="claude-opus-4-5",
 max_tokens=1024,
 tools=tools,
 messages=[{"role":"user","content":"Book me a haircut in Atlanta for Saturday under $50"}],
)

Option 4: Plain REST

curl -X POST https://agent-broker-edge.basil-agent.workers.dev/ops/find_business \
 -H "X-Agent-Identity: $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{
 "vertical": "personal_services",
 "location": {"zip_or_city": "30309"},
 "capability": "haircut"
 }'

Discovery surfaces

We're discoverable through every protocol agents currently use:

Protocol	URL
MCP	`https://agent-broker-edge.basil-agent.workers.dev/mcp`
MCP descriptor	`https://agent-broker-edge.basil-agent.workers.dev/.well-known/mcp.json`
OpenAI ChatGPT plugin	`https://agent-broker-edge.basil-agent.workers.dev/.well-known/ai-plugin.json`
OpenAI function tools	`https://agent-broker-edge.basil-agent.workers.dev/.well-known/openai-tools.json`
Anthropic tool_use	`https://agent-broker-edge.basil-agent.workers.dev/.well-known/anthropic-tools.json`
A2A (Agent-to-Agent)	`https://agent-broker-edge.basil-agent.workers.dev/.well-known/agents.json`
llms.txt	`https://agent-broker-edge.basil-agent.workers.dev/llms.txt`
OpenAPI 3.1	`https://agent-broker-edge.basil-agent.workers.dev/openapi.yaml`
Capability manifest	`https://agent-broker-edge.basil-agent.workers.dev/manifest`
Service discovery card	`https://agent-broker-edge.basil-agent.workers.dev/.well-known/agent-service`

Why agents pick us (measured, not assumed)

From our agent-simulation harness — 168 trials × 3 personas (cost / quality / latency) across 56 tasks, with noisy agent perception (±15% on price, ±10% on quality, ±20% on latency):

Persona	Selection rate	Success when selected	WinRate
cost_minimizer	94.6%	88.7%	0.839
quality_maximizer	91.1%	88.2%	0.804
latency_sensitive	91.7%	88.3%	0.810
Aggregate	92.5%	88.4%	0.818

We deliberately included tasks where we should lose — out-of-region SMBs (Tokyo / Mumbai / Berlin), complex web automation, trivial lookups — and the simulation correctly routes those to competitors. See BENCHMARKS.md.

Compliance posture

Every outbound communication passes through compliance/pre_check():

Content classification (gambling / lending / cannabis / adult / spam) — blocks restricted categories.
Opt-out check — TCPA STOP keyword, GDPR right-to-be-forgotten, CASL.
Consent check for marketing — TCPA written consent, GDPR opt-in, CASL implied/express.
10DLC campaign-registry check for US SMS.
Two-party recording consent for CA / FL / IL / MD / MA / MT / NV / NH / PA / WA.
Audit log entry (PII stored as SHA-256 hash, never plaintext).

Compliance violations surface as ComplianceViolationError → compliance_violation API error. Never silently dropped, never bypassed by middleware.

Architecture

AI agent → Cloudflare Worker edge (agent-broker-edge.basil-agent.workers.dev)
 ├── Discovery + MCP read → embedded snapshots 40–70 ms
 └── tools/call + /ops/* → proxy to origin 170–190 ms
 ↓
 Python FastAPI on Render (smb-broker.onrender.com)
 Cron */2 keeps Render warm — cold starts eliminated

The Python service exposes 13 operations over REST + MCP + .well-known surfaces. Each handler validates input with Pydantic models, runs through compliance/pre_check, executes via channel-fallback (direct_api → voice_ai → sms → email → web_form), and writes an immutable OutcomeReceipt to the outcome store. Async operations return pending_async. Idempotency is keyed by (agent_id, operation, idempotency_key) with 24h TTL.

Full architecture: docs/architecture.md · Edge layer: edge/README.md

Repo layout

service-root/
├── core/ # 12 operation handlers + shared Pydantic models
├── channels/ # Twilio, SendGrid, Vapi, Bland, Cal.com, Playwright
├── compliance/ # pre_check, jurisdiction_rules, consent_store, audit_log
├── reliability/ # retry, circuit_breaker, channel_fallback, async_runner
├── billing/ # meter, budget_guard, receipt_signer, pricing_tiers
├── telemetry/ # tracer, log_redactor, metrics_emitter
├── storage/ # outcome_store, idempotency_store
├── supply/ # smb_directory (20+ seed SMBs)
├── onboarding/ # self_serve, verification_flow, channel_capture
├── feedback/ # failure_classifier, attribution_engine, outcome_evaluator
├── optimizer/ # ab_router, selection_analytics, weekly_report
├── agent_interface/ # manifest_server, mcp_server, well_known, identity, webhooks, self_test
├── manifest/ # manifest.json, mcp_tools.json, openapi.yaml
├── api/ # errors.md, identity.md, async.md
├── docs/ # mission, architecture, compliance, ADRs
├── deploy/ # Dockerfile, docker-compose.yml, .ci/
├── tests/ # unit, contract, compliance, fault_injection, agent_sim
├── reports/ # agent_sim_report.json, weekly winrate reports
├── main.py # FastAPI entry point
├── config.py # Centralized config from env
└── requirements.txt

Local development

# 1. Clone & install
pip install -r requirements.txt
# 2. Run the test suite
python -m pytest tests/ -q
# 3. Run the agent simulation
python -m tests.agent_sim.harness
# 4. Run the self-test
python -c "import asyncio; from agent_interface.self_test import run_self_test; print(asyncio.run(run_self_test()).all_passed)"
# 5. Start the API
python main.py
# → http://localhost:8000/docs (Swagger)
# → http://localhost:8000/manifest
# → http://localhost:8000/mcp

Or with Docker:

docker compose -f deploy/docker-compose.yml up

Documentation index

Mission — north-star metric, scope, who we are NOT
Architecture — module map, data flow, fallback chains
Compliance — full jurisdiction matrix, pre-check sequence
API errors — 16 error codes with retry semantics
API identity — Agent-Identity JWT spec
API async — execution profiles, polling rules, webhook contract
Agent integration guide — copy-paste examples for every protocol
Benchmarks — measured WinRate, latency, cost vs alternatives
Pricing — 5 revenue streams with year-1 / year-2 forecasts
Security — production hardening checklist
Release notes v0.1
Next steps — current priorities (edge live; bottleneck is distribution)
ADRs — architecture decision records

License

Proprietary. Contact for licensing terms.

Try in Playground

Server Config

{
 "mcpServers": {
 "agent-broker": {
 "url": "https://agent-broker-edge.basil-agent.workers.dev/mcp"
 }
 }
}

Build with ShipAny.

URL: https://mcp.so/server/agent-broker/basilalshukaili

⇱ Agent Broker MCP Server