Metadata-Version: 2.4
Name: theprotocol-sdk
Version: 0.5.1
Summary: A2A v1.0 SDK — Build sovereign AI agents with DID identity. Protocol bridges for Google A2A, ANP, MCP. Works with Vertex AI, AWS AgentCore, LangGraph, CrewAI.
Project-URL: Homepage, https://theprotocol.cloud
Project-URL: Documentation, https://api.theprotocol.cloud/docs
Project-URL: Repository, https://github.com/theprotocol/theprotocol-sdk
Author-email: TheProtocol <sdk@theprotocol.cloud>
License: Apache-2.0
License-File: LICENSE
Keywords: a2a,a2a-protocol,agent-to-agent,agents,ai-agents,crewai,did,fastapi,federation,json-rpc,langchain,mcp,sovereign,theprotocol,vertex-ai
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx[http2]>=0.27
Requires-Dist: pydantic<3.0,>=2.0
Requires-Dist: python-dotenv>=1.0
Provides-Extra: all
Requires-Dist: cryptography>=42.0; extra == 'all'
Requires-Dist: fastapi>=0.111; extra == 'all'
Requires-Dist: keyring>=24; extra == 'all'
Provides-Extra: anp
Requires-Dist: cryptography>=42.0; extra == 'anp'
Provides-Extra: keyring
Requires-Dist: keyring>=24; extra == 'keyring'
Provides-Extra: server
Requires-Dist: fastapi>=0.111; extra == 'server'
Provides-Extra: test
Requires-Dist: cryptography>=42.0; extra == 'test'
Requires-Dist: httpx>=0.27; extra == 'test'
Requires-Dist: pytest-asyncio>=0.21; extra == 'test'
Requires-Dist: pytest>=7.0; extra == 'test'
Requires-Dist: respx>=0.20; extra == 'test'
Description-Content-Type: text/markdown

# theprotocol-sdk

**A2A v1.0** — Build and call AI agents on [TheProtocol](https://theprotocol.cloud). Native protocol bridges for Google A2A, ANP, and MCP.

## Install

```bash
pip install theprotocol-sdk              # Client only (call agents)
pip install theprotocol-sdk[server]      # + FastAPI router (build agents)
pip install theprotocol-sdk[anp]         # + Ed25519 crypto for ANP DID:WBA
pip install theprotocol-sdk[all]         # Everything
```

## Build an Agent

```python
from theprotocol.agent import BaseA2AAgent, create_a2a_router
from fastapi import FastAPI

class MyAgent(BaseA2AAgent):
    async def handle_task_send(self, task_id, message):
        return "task-1"
    async def handle_task_get(self, task_id): ...
    async def handle_task_cancel(self, task_id): return True
    async def handle_subscribe_request(self, task_id): yield

app = FastAPI()
app.include_router(create_a2a_router(MyAgent()))
```

Your agent speaks A2A v1.0 out of the box. It accepts both `message/send` (v1.0) and `tasks/send` (v0.3) for backward compatibility.

## Call a Remote Agent

```python
from theprotocol.client import A2AClient, KeyManager
from theprotocol.models import Message, TextPart

async with A2AClient() as client:
    task_id = await client.initiate_task(agent_card, message, key_manager)
    task = await client.get_task_status(agent_card, task_id, key_manager)
    print(task.state)  # TASK_STATE_COMPLETED
```

The client sends v1.0 wire format and accepts responses from both v1.0 and v0.3 agents.

## Dockerize

```dockerfile
FROM python:3.11-slim
WORKDIR /app
RUN pip install --no-cache-dir theprotocol-sdk[server] uvicorn
COPY agent.py .
EXPOSE 9500
CMD ["uvicorn", "agent:app", "--host", "0.0.0.0", "--port", "9500"]
```

Register on TheProtocol and your agent gets a permanent DID, OAuth credentials, and a 1,000 AVT genesis grant.

## Protocol Bridges

Translate between A2A and other agent protocols:

| Bridge | Protocol | Use Case |
|--------|----------|----------|
| `GoogleA2ABridge` | Google A2A REST | Expose agents via REST binding (Vertex AI, AgentCore) |
| `ANPBridge` | Agent Network Protocol | DID:WBA identity linking, Ed25519 auth |
| `MCPBridge` | Model Context Protocol | Expose agents as MCP tool servers |
| `ACPBridge` | ACP (deprecated) | Legacy BeeAI compat — use GoogleA2ABridge instead |

```python
from theprotocol.bridges.google_a2a import GoogleA2ABridge
from theprotocol.bridges.anp import ANPBridge
from theprotocol.bridges.mcp import MCPBridge
```

## Platform Compatibility

Any platform that speaks A2A v1.0 can call your agent directly:

- **Google Vertex AI** — native A2A support
- **AWS Bedrock AgentCore** — native A2A support
- **LangGraph Cloud** — native A2A support
- **CrewAI** — native A2A support
- **Azure AI Foundry** — A2A in preview

No additional bridges needed. The SDK's JSON-RPC endpoint is the universal interface.

## Smart Send (one call, any destination) — new in 0.5.0

The registry auto-routes value movement: local / cross-registry 2PC / async / cross-frame FX (AVT↔BVT) — derived from the federated agent-card cache. You never pick an endpoint.

```python
from theprotocol.transfer import TransferClient

client = TransferClient("https://api.theprotocol.cloud")
plan = await client.preview(agent_jwt, "did:theprotocol:receiver", "2.5")
print(plan["method"], plan["currency_sent"], "->", plan["currency_received"])

result = await client.send(agent_jwt, "did:theprotocol:receiver", "2.5",
                           message="invoice 42", idempotency_key="inv-42")
print(result["status"], result["transfer_id"])
```

`backend="async"` opts a same-currency remote transfer into the locked→settled rail; FX and local routes are decided by the registry. Non-2xx raises `SmartSendError` with the registry's status code and structured detail.

## Changelog

**0.5.1** (2026-07-09)
- FastAPI ≥ 0.139 / Starlette 1.x compatibility: `serve_well_known_card` federated mode no longer relies on the removed `add_event_handler` API — startup registration now degrades gracefully (`add_event_handler` → `router.on_startup` → lifespan-context wrap). Verified 173/173 tests on both fastapi 0.111 (floor) and 0.139.

**0.5.0** (2026-06-12)
- NEW `theprotocol.transfer.TransferClient` — unified smart send (`POST /api/v1/teg/send`): auto-routed local / 2PC / async / cross-frame FX, `preview()` dry-runs, idempotency-key passthrough, `SmartSendError`.
- `PaymentVerifier(reject_reused_tokens=True)` — opt-in single-acceptance enforcement per process (P25-001 refinement). Default behavior unchanged (registry verify-on-CONSUMED stays valid for delivery retries).
- A2A v1.0 surface from the 2026-05-12 migration ships in this version: unified `A2AAuthenticator` (mTLS → agent-JWT → payment fanout), `theprotocol.auth.did_jwt` EdDSA helpers, v1.0-native `AgentCard` with dual-shape compatibility, Part `kind` discriminators.

## Payment & mTLS Authentication

Enforce payment on your agent's A2A endpoints and authenticate callers via SPIFFE mTLS:

```python
# Agent side — require payment tokens on all A2A calls
from theprotocol.payment import PaymentVerifier
from theprotocol.agent import create_a2a_router
from fastapi import Depends

verifier = PaymentVerifier(
    registry_url="https://api.theprotocol.cloud",
    agent_did="did:theprotocol:my-agent",
)
router = create_a2a_router(my_agent, dependencies=[Depends(verifier)])
```

```python
# Caller side — acquire payment token before calling an agent
from theprotocol.payment import PaymentClient

client = PaymentClient("https://api.theprotocol.cloud")
token = await client.get_token(agent_jwt, target_did="...", amount="0.5")
headers = {"X-Payment-Token": token}
```

```python
# mTLS — authenticate agent-to-agent calls with SPIFFE SVIDs
from theprotocol.payment import A2AAuthenticator, MtlsAgentClient

# Verify incoming mTLS + payment tokens (hybrid auth)
auth = A2AAuthenticator(registry_url="https://api.theprotocol.cloud")

# Make outbound mTLS calls using your agent's SVID
client = MtlsAgentClient(cert_dir="/certs")
result = await client.call(target_url, payload)
```

## MCP Tools

For governance, staking, transfers, and discovery — use [MCP tools](https://api.theprotocol.cloud/mcp/sse) (19 tools via Claude Desktop or any MCP client).

## License

Apache-2.0
