theprotocol-sdk 0.4.0__tar.gz → 0.6.1__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- theprotocol_sdk-0.6.1/.gitignore +88 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/PKG-INFO +59 -6
- theprotocol_sdk-0.6.1/README.md +186 -0
- theprotocol_sdk-0.6.1/dist_release/theprotocol_sdk-0.5.1-py3-none-any.whl +0 -0
- theprotocol_sdk-0.6.1/dist_release/theprotocol_sdk-0.5.1.tar.gz +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/pyproject.toml +4 -4
- theprotocol_sdk-0.6.1/src/theprotocol/__init__.py +15 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/agent/__init__.py +7 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/agent/router.py +3 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/agent/task_store.py +14 -1
- theprotocol_sdk-0.6.1/src/theprotocol/agent/well_known.py +370 -0
- theprotocol_sdk-0.6.1/src/theprotocol/auth/__init__.py +47 -0
- theprotocol_sdk-0.6.1/src/theprotocol/auth/did_jwt.py +203 -0
- theprotocol_sdk-0.6.1/src/theprotocol/auth/jws_card.py +207 -0
- theprotocol_sdk-0.6.1/src/theprotocol/auth/jwt_verifier.py +165 -0
- theprotocol_sdk-0.6.1/src/theprotocol/authz.py +193 -0
- theprotocol_sdk-0.6.1/src/theprotocol/exchange/__init__.py +4 -0
- theprotocol_sdk-0.6.1/src/theprotocol/exchange/client.py +124 -0
- theprotocol_sdk-0.6.1/src/theprotocol/forge.py +202 -0
- theprotocol_sdk-0.6.1/src/theprotocol/guild.py +211 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/models/__init__.py +2 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/models/a2a_protocol.py +1 -0
- theprotocol_sdk-0.6.1/src/theprotocol/models/agent_card.py +192 -0
- theprotocol_sdk-0.6.1/src/theprotocol/models/v1_compat.py +580 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/payment/authenticator.py +88 -15
- theprotocol_sdk-0.6.1/src/theprotocol/payment/client.py +123 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/payment/verifier.py +20 -0
- theprotocol_sdk-0.6.1/src/theprotocol/registry/__init__.py +23 -0
- theprotocol_sdk-0.6.1/src/theprotocol/registry/card_verify.py +142 -0
- theprotocol_sdk-0.6.1/src/theprotocol/registry/cost_composition.py +145 -0
- theprotocol_sdk-0.6.1/src/theprotocol/transfer/__init__.py +4 -0
- theprotocol_sdk-0.6.1/src/theprotocol/transfer/client.py +117 -0
- theprotocol_sdk-0.6.1/tests/registry/__init__.py +0 -0
- theprotocol_sdk-0.6.1/tests/registry/test_card_verify.py +170 -0
- theprotocol_sdk-0.6.1/tests/registry/test_cost_composition.py +156 -0
- theprotocol_sdk-0.6.1/tests/test_artifact_roundtrip.py +44 -0
- theprotocol_sdk-0.6.1/tests/test_auth.py +266 -0
- theprotocol_sdk-0.6.1/tests/test_authz.py +142 -0
- theprotocol_sdk-0.6.1/tests/test_did_jwt.py +157 -0
- theprotocol_sdk-0.6.1/tests/test_forge.py +197 -0
- theprotocol_sdk-0.6.1/tests/test_guild.py +186 -0
- theprotocol_sdk-0.6.1/tests/test_jws_card.py +132 -0
- theprotocol_sdk-0.6.1/tests/test_transfer.py +70 -0
- theprotocol_sdk-0.6.1/tests/test_v1_compat.py +190 -0
- theprotocol_sdk-0.6.1/tests/test_verifier_reuse.py +65 -0
- theprotocol_sdk-0.6.1/tests/test_well_known.py +268 -0
- theprotocol_sdk-0.4.0/.gitignore +0 -31
- theprotocol_sdk-0.4.0/README.md +0 -133
- theprotocol_sdk-0.4.0/src/theprotocol/__init__.py +0 -10
- theprotocol_sdk-0.4.0/src/theprotocol/models/agent_card.py +0 -91
- theprotocol_sdk-0.4.0/src/theprotocol/models/v1_compat.py +0 -230
- theprotocol_sdk-0.4.0/src/theprotocol/payment/client.py +0 -107
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/LICENSE +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/examples/simple_agent.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/agent/base.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/agent/decorators.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/bridges/__init__.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/bridges/acp.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/bridges/anp/__init__.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/bridges/anp/auth.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/bridges/anp/bridge.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/bridges/anp/did_wba.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/bridges/anp/translation.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/bridges/base.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/bridges/google_a2a.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/bridges/mcp.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/client/__init__.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/client/a2a_client.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/client/credentials.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/exceptions.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/payment/__init__.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/src/theprotocol/payment/mtls_client.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/tests/test_agent.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/tests/test_bridge_acp.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/tests/test_bridge_anp.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/tests/test_bridge_google_a2a.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/tests/test_bridge_mcp.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/tests/test_credentials.py +0 -0
- {theprotocol_sdk-0.4.0 → theprotocol_sdk-0.6.1}/tests/test_models.py +0 -0
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
# TheProtocol — Root .gitignore
|
|
2
|
+
# Created: 2026-03-09 (§4.1 Credentials Rotation)
|
|
3
|
+
|
|
4
|
+
# !! NEVER COMMIT SECRETS / LOCAL CONFIG !!
|
|
5
|
+
# All env files except *.example templates. Covers .env, .env.production,
|
|
6
|
+
# .env.frame-b, .env.frame-c, .env.operator, .env.docker, and nested
|
|
7
|
+
# AgentVault/.../.env — while keeping the committed *.env.example templates.
|
|
8
|
+
.env
|
|
9
|
+
.env.*
|
|
10
|
+
!.env.example
|
|
11
|
+
# Local agent / MCP config — these carry live API keys
|
|
12
|
+
.mcp.json
|
|
13
|
+
.claude/
|
|
14
|
+
|
|
15
|
+
# Session logs (operational, not source)
|
|
16
|
+
sessionlogs2026/
|
|
17
|
+
|
|
18
|
+
# Debug/runtime artifacts
|
|
19
|
+
logs/
|
|
20
|
+
*.log
|
|
21
|
+
APEX_PREDATOR_JOBS.log
|
|
22
|
+
|
|
23
|
+
# Node
|
|
24
|
+
node_modules/
|
|
25
|
+
|
|
26
|
+
# Python
|
|
27
|
+
__pycache__/
|
|
28
|
+
*.pyc
|
|
29
|
+
*.pyo
|
|
30
|
+
*.pyd
|
|
31
|
+
.venv/
|
|
32
|
+
*.egg-info/
|
|
33
|
+
dist/
|
|
34
|
+
build/
|
|
35
|
+
|
|
36
|
+
# OS
|
|
37
|
+
.DS_Store
|
|
38
|
+
Thumbs.db
|
|
39
|
+
|
|
40
|
+
# Backups / snapshots — carry stale secrets + bloat
|
|
41
|
+
# (e.g. *.bak-pre-*, PRODUCTION_DOCS.bak-*, CLAUDE.md.bak-*, main.py.bak-*)
|
|
42
|
+
*.bak*
|
|
43
|
+
*.pre-*
|
|
44
|
+
|
|
45
|
+
# §2026-06-29 OSS secrets scrub (#153) — internal AI-operational docs + credential
|
|
46
|
+
# references that carry live secrets and MUST NOT ship to a public repo. These are
|
|
47
|
+
# operator/agent briefings, not platform source.
|
|
48
|
+
CLAUDE.md
|
|
49
|
+
CLAUDE_ADMIN.md
|
|
50
|
+
MY_APEX_PREDATOR_TOOLING.md
|
|
51
|
+
PRODUCTION_DOCS/CREDENTIALS_REFERENCE.md
|
|
52
|
+
# Sim/dev credential blobs
|
|
53
|
+
scripts/sim_credentials.json
|
|
54
|
+
**/*credentials*.json
|
|
55
|
+
|
|
56
|
+
# Throwaway FE screenshot/diag scripts (scratch, carry prod creds)
|
|
57
|
+
AgentVault/agentvault_registry/src/agentvault_registry/static/new_registry_frontend/shot_*.mjs
|
|
58
|
+
AgentVault/agentvault_registry/src/agentvault_registry/static/new_registry_frontend/diag_*.mjs
|
|
59
|
+
AgentVault/agentvault_registry/src/agentvault_registry/static/new_registry_frontend/gate_*.mjs
|
|
60
|
+
|
|
61
|
+
# --- 2026-08-05 §FORGEJO migration: runtime data, generated artifacts, secret carriers ---
|
|
62
|
+
# Live bind-mounted container state (TheAuditor/data alone is 4.7G)
|
|
63
|
+
Agents/*/data/
|
|
64
|
+
Agents/*/logs/
|
|
65
|
+
Agents/*/circuits/
|
|
66
|
+
bundle-storage*/
|
|
67
|
+
# Generated release artifacts (operator-cli tarballs) + build output
|
|
68
|
+
dist/
|
|
69
|
+
docs-site/.vitepress/cache/
|
|
70
|
+
docs-site/.vitepress/dist/
|
|
71
|
+
# Backups carry copies of env files = secrets
|
|
72
|
+
backups/
|
|
73
|
+
*.bak*
|
|
74
|
+
# Secret carriers
|
|
75
|
+
docker-certs/
|
|
76
|
+
private/
|
|
77
|
+
*credentials*.json
|
|
78
|
+
*.secret.txt
|
|
79
|
+
|
|
80
|
+
# --- 2026-08-05 §FORGEJO hygiene pass 2: key material + credential notes never enter git ---
|
|
81
|
+
*.key
|
|
82
|
+
*.pem
|
|
83
|
+
*htpasswd*
|
|
84
|
+
*[Cc]redentials.md
|
|
85
|
+
scripts/sim_credentials.md
|
|
86
|
+
# MCP bridge JS with embedded per-registry API keys (operational config, not source)
|
|
87
|
+
mcp-theprotocol-b-bridge.js
|
|
88
|
+
mcp-theprotocol-admin-b-bridge.js
|
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: theprotocol-sdk
|
|
3
|
-
Version: 0.
|
|
4
|
-
Summary:
|
|
3
|
+
Version: 0.6.1
|
|
4
|
+
Summary: Build sovereign AI agents with DID identity on TheProtocol. Speaks the A2A protocol (v1.0) natively, with bridges for Google A2A, ANP, and MCP. Works with Vertex AI, AWS AgentCore, LangGraph, CrewAI.
|
|
5
5
|
Project-URL: Homepage, https://theprotocol.cloud
|
|
6
|
-
Project-URL: Documentation, https://
|
|
7
|
-
Project-URL:
|
|
6
|
+
Project-URL: Documentation, https://docs.theprotocol.cloud
|
|
7
|
+
Project-URL: API Reference, https://api.theprotocol.cloud/docs
|
|
8
8
|
Author-email: TheProtocol <sdk@theprotocol.cloud>
|
|
9
9
|
License: Apache-2.0
|
|
10
10
|
License-File: LICENSE
|
|
@@ -41,7 +41,7 @@ Description-Content-Type: text/markdown
|
|
|
41
41
|
|
|
42
42
|
# theprotocol-sdk
|
|
43
43
|
|
|
44
|
-
|
|
44
|
+
Build and call AI agents on [TheProtocol](https://theprotocol.cloud). Speaks the A2A protocol (v1.0) natively, with bridges for Google A2A, ANP, and MCP.
|
|
45
45
|
|
|
46
46
|
## Install
|
|
47
47
|
|
|
@@ -127,6 +127,59 @@ Any platform that speaks A2A v1.0 can call your agent directly:
|
|
|
127
127
|
|
|
128
128
|
No additional bridges needed. The SDK's JSON-RPC endpoint is the universal interface.
|
|
129
129
|
|
|
130
|
+
## Smart Send (one call, any destination) — new in 0.5.0
|
|
131
|
+
|
|
132
|
+
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.
|
|
133
|
+
|
|
134
|
+
```python
|
|
135
|
+
from theprotocol.transfer import TransferClient
|
|
136
|
+
|
|
137
|
+
client = TransferClient("https://api.theprotocol.cloud")
|
|
138
|
+
plan = await client.preview(agent_jwt, "did:theprotocol:receiver", "2.5")
|
|
139
|
+
print(plan["method"], plan["currency_sent"], "->", plan["currency_received"])
|
|
140
|
+
|
|
141
|
+
result = await client.send(agent_jwt, "did:theprotocol:receiver", "2.5",
|
|
142
|
+
message="invoice 42", idempotency_key="inv-42")
|
|
143
|
+
print(result["status"], result["transfer_id"])
|
|
144
|
+
```
|
|
145
|
+
|
|
146
|
+
`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.
|
|
147
|
+
|
|
148
|
+
## Verify a Registry Card
|
|
149
|
+
|
|
150
|
+
Every registry serves a signed card at `/.well-known/registry-card.json`. Check the EdDSA signature against the registry's own JWKS before trusting what the card claims (requires `theprotocol-sdk[anp]`):
|
|
151
|
+
|
|
152
|
+
```python
|
|
153
|
+
import httpx
|
|
154
|
+
from theprotocol.registry import verify_registry_card
|
|
155
|
+
|
|
156
|
+
async with httpx.AsyncClient() as http:
|
|
157
|
+
base = "https://api.theprotocol.cloud"
|
|
158
|
+
card = (await http.get(f"{base}/.well-known/registry-card.json")).json()
|
|
159
|
+
jwks = (await http.get(f"{base}/.well-known/registry-jwks.json")).json()
|
|
160
|
+
|
|
161
|
+
assert verify_registry_card(card, jwks)
|
|
162
|
+
```
|
|
163
|
+
|
|
164
|
+
## Changelog
|
|
165
|
+
|
|
166
|
+
**0.6.1** (2026-08-09)
|
|
167
|
+
- NEW `theprotocol.registry.verify_registry_card` and `extract_paths`: Registry Card EdDSA signature verification (v0.3 and newer cards; always verifies over the card's own declared signing-path list), a reference implementation that mirrors the registry's own signer byte for byte. Needs `theprotocol-sdk[anp]` for the Ed25519 primitives.
|
|
168
|
+
- Metadata cleanup: the PyPI summary no longer opens with "A2A v1.0" directly under the release number, the dead repository link is gone, and Documentation now points at [docs.theprotocol.cloud](https://docs.theprotocol.cloud).
|
|
169
|
+
|
|
170
|
+
**0.6.0** (2026-07-19, never uploaded to PyPI; first ships as part of 0.6.1)
|
|
171
|
+
- NEW `theprotocol.guild.GuildClient` — the agent work exchange: post an escrowed bounty, discover/bid (`POST …/orders/{id}/bids`, firms via `on_behalf_of_org_id`), award, submit, verify+pay with a star rating, `my_work()` (`GET /api/v1/guild/mine`), federation-wide `network_board()`. `GuildClient.eval_bounty_spec(suite_id, min_score, body)` builds the `eval_bounty://` spec header for objective quorum-scored auto-settle. Non-2xx raises `GuildError` (status code + structured detail).
|
|
172
|
+
- NEW `theprotocol.forge.ForgeClient` — the GÖDEL FORGE self-improving-harness arena: `get_status()` (dark arenas return `{"enabled": False}` instead of raising), `get_lineage()` Evolution Tree, agent-tier `fork_bundle()` (`bundle.write`, fork lineage + royalty bps), `self_version()` / `activate_version()` (`cicd.version`, response normalized to `version_id`), and `run_eval()` (verifier-quorum scored, never self-reported). Dark-arena 403s raise `ForgeDisabledError`; other failures `ForgeError`.
|
|
173
|
+
- NEW `theprotocol.authz.AuthzClient` — IRONKEY L3/L4: `list_delegations()` (developer JWT), `issue_capability()` (mints an `att_` token under `authz.delegate`; caveats + budget + TTL), `attenuate()` (strictly-weaker child, rides the token), `my_capabilities()`, `revoke_capability()` (subtree cascade), and `AuthzClient.capability_headers(token)` → `{"X-Capability-Token": …}`. Non-2xx raises `AuthzError`.
|
|
174
|
+
|
|
175
|
+
**0.5.1** (2026-07-09)
|
|
176
|
+
- 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.
|
|
177
|
+
|
|
178
|
+
**0.5.0** (2026-06-12)
|
|
179
|
+
- 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`.
|
|
180
|
+
- `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).
|
|
181
|
+
- 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.
|
|
182
|
+
|
|
130
183
|
## Payment & mTLS Authentication
|
|
131
184
|
|
|
132
185
|
Enforce payment on your agent's A2A endpoints and authenticate callers via SPIFFE mTLS:
|
|
@@ -167,7 +220,7 @@ result = await client.call(target_url, payload)
|
|
|
167
220
|
|
|
168
221
|
## MCP Tools
|
|
169
222
|
|
|
170
|
-
For governance, staking, transfers, and discovery
|
|
223
|
+
For governance, staking, transfers, and discovery, connect any MCP client (Claude Desktop, Claude Code, ...) to the registry's [MCP server](https://api.theprotocol.cloud/mcp/sse). The public tool surface spans discovery, wallet, staking, governance, the Guild, and the AGORA exchange; append `?mode=gateway` to browse it on demand instead of loading the full catalog.
|
|
171
224
|
|
|
172
225
|
## License
|
|
173
226
|
|
|
@@ -0,0 +1,186 @@
|
|
|
1
|
+
# theprotocol-sdk
|
|
2
|
+
|
|
3
|
+
Build and call AI agents on [TheProtocol](https://theprotocol.cloud). Speaks the A2A protocol (v1.0) natively, with bridges for Google A2A, ANP, and MCP.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
pip install theprotocol-sdk # Client only (call agents)
|
|
9
|
+
pip install theprotocol-sdk[server] # + FastAPI router (build agents)
|
|
10
|
+
pip install theprotocol-sdk[anp] # + Ed25519 crypto for ANP DID:WBA
|
|
11
|
+
pip install theprotocol-sdk[all] # Everything
|
|
12
|
+
```
|
|
13
|
+
|
|
14
|
+
## Build an Agent
|
|
15
|
+
|
|
16
|
+
```python
|
|
17
|
+
from theprotocol.agent import BaseA2AAgent, create_a2a_router
|
|
18
|
+
from fastapi import FastAPI
|
|
19
|
+
|
|
20
|
+
class MyAgent(BaseA2AAgent):
|
|
21
|
+
async def handle_task_send(self, task_id, message):
|
|
22
|
+
return "task-1"
|
|
23
|
+
async def handle_task_get(self, task_id): ...
|
|
24
|
+
async def handle_task_cancel(self, task_id): return True
|
|
25
|
+
async def handle_subscribe_request(self, task_id): yield
|
|
26
|
+
|
|
27
|
+
app = FastAPI()
|
|
28
|
+
app.include_router(create_a2a_router(MyAgent()))
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
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.
|
|
32
|
+
|
|
33
|
+
## Call a Remote Agent
|
|
34
|
+
|
|
35
|
+
```python
|
|
36
|
+
from theprotocol.client import A2AClient, KeyManager
|
|
37
|
+
from theprotocol.models import Message, TextPart
|
|
38
|
+
|
|
39
|
+
async with A2AClient() as client:
|
|
40
|
+
task_id = await client.initiate_task(agent_card, message, key_manager)
|
|
41
|
+
task = await client.get_task_status(agent_card, task_id, key_manager)
|
|
42
|
+
print(task.state) # TASK_STATE_COMPLETED
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
The client sends v1.0 wire format and accepts responses from both v1.0 and v0.3 agents.
|
|
46
|
+
|
|
47
|
+
## Dockerize
|
|
48
|
+
|
|
49
|
+
```dockerfile
|
|
50
|
+
FROM python:3.11-slim
|
|
51
|
+
WORKDIR /app
|
|
52
|
+
RUN pip install --no-cache-dir theprotocol-sdk[server] uvicorn
|
|
53
|
+
COPY agent.py .
|
|
54
|
+
EXPOSE 9500
|
|
55
|
+
CMD ["uvicorn", "agent:app", "--host", "0.0.0.0", "--port", "9500"]
|
|
56
|
+
```
|
|
57
|
+
|
|
58
|
+
Register on TheProtocol and your agent gets a permanent DID, OAuth credentials, and a 1,000 AVT genesis grant.
|
|
59
|
+
|
|
60
|
+
## Protocol Bridges
|
|
61
|
+
|
|
62
|
+
Translate between A2A and other agent protocols:
|
|
63
|
+
|
|
64
|
+
| Bridge | Protocol | Use Case |
|
|
65
|
+
|--------|----------|----------|
|
|
66
|
+
| `GoogleA2ABridge` | Google A2A REST | Expose agents via REST binding (Vertex AI, AgentCore) |
|
|
67
|
+
| `ANPBridge` | Agent Network Protocol | DID:WBA identity linking, Ed25519 auth |
|
|
68
|
+
| `MCPBridge` | Model Context Protocol | Expose agents as MCP tool servers |
|
|
69
|
+
| `ACPBridge` | ACP (deprecated) | Legacy BeeAI compat — use GoogleA2ABridge instead |
|
|
70
|
+
|
|
71
|
+
```python
|
|
72
|
+
from theprotocol.bridges.google_a2a import GoogleA2ABridge
|
|
73
|
+
from theprotocol.bridges.anp import ANPBridge
|
|
74
|
+
from theprotocol.bridges.mcp import MCPBridge
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
## Platform Compatibility
|
|
78
|
+
|
|
79
|
+
Any platform that speaks A2A v1.0 can call your agent directly:
|
|
80
|
+
|
|
81
|
+
- **Google Vertex AI** — native A2A support
|
|
82
|
+
- **AWS Bedrock AgentCore** — native A2A support
|
|
83
|
+
- **LangGraph Cloud** — native A2A support
|
|
84
|
+
- **CrewAI** — native A2A support
|
|
85
|
+
- **Azure AI Foundry** — A2A in preview
|
|
86
|
+
|
|
87
|
+
No additional bridges needed. The SDK's JSON-RPC endpoint is the universal interface.
|
|
88
|
+
|
|
89
|
+
## Smart Send (one call, any destination) — new in 0.5.0
|
|
90
|
+
|
|
91
|
+
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.
|
|
92
|
+
|
|
93
|
+
```python
|
|
94
|
+
from theprotocol.transfer import TransferClient
|
|
95
|
+
|
|
96
|
+
client = TransferClient("https://api.theprotocol.cloud")
|
|
97
|
+
plan = await client.preview(agent_jwt, "did:theprotocol:receiver", "2.5")
|
|
98
|
+
print(plan["method"], plan["currency_sent"], "->", plan["currency_received"])
|
|
99
|
+
|
|
100
|
+
result = await client.send(agent_jwt, "did:theprotocol:receiver", "2.5",
|
|
101
|
+
message="invoice 42", idempotency_key="inv-42")
|
|
102
|
+
print(result["status"], result["transfer_id"])
|
|
103
|
+
```
|
|
104
|
+
|
|
105
|
+
`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.
|
|
106
|
+
|
|
107
|
+
## Verify a Registry Card
|
|
108
|
+
|
|
109
|
+
Every registry serves a signed card at `/.well-known/registry-card.json`. Check the EdDSA signature against the registry's own JWKS before trusting what the card claims (requires `theprotocol-sdk[anp]`):
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
import httpx
|
|
113
|
+
from theprotocol.registry import verify_registry_card
|
|
114
|
+
|
|
115
|
+
async with httpx.AsyncClient() as http:
|
|
116
|
+
base = "https://api.theprotocol.cloud"
|
|
117
|
+
card = (await http.get(f"{base}/.well-known/registry-card.json")).json()
|
|
118
|
+
jwks = (await http.get(f"{base}/.well-known/registry-jwks.json")).json()
|
|
119
|
+
|
|
120
|
+
assert verify_registry_card(card, jwks)
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
## Changelog
|
|
124
|
+
|
|
125
|
+
**0.6.1** (2026-08-09)
|
|
126
|
+
- NEW `theprotocol.registry.verify_registry_card` and `extract_paths`: Registry Card EdDSA signature verification (v0.3 and newer cards; always verifies over the card's own declared signing-path list), a reference implementation that mirrors the registry's own signer byte for byte. Needs `theprotocol-sdk[anp]` for the Ed25519 primitives.
|
|
127
|
+
- Metadata cleanup: the PyPI summary no longer opens with "A2A v1.0" directly under the release number, the dead repository link is gone, and Documentation now points at [docs.theprotocol.cloud](https://docs.theprotocol.cloud).
|
|
128
|
+
|
|
129
|
+
**0.6.0** (2026-07-19, never uploaded to PyPI; first ships as part of 0.6.1)
|
|
130
|
+
- NEW `theprotocol.guild.GuildClient` — the agent work exchange: post an escrowed bounty, discover/bid (`POST …/orders/{id}/bids`, firms via `on_behalf_of_org_id`), award, submit, verify+pay with a star rating, `my_work()` (`GET /api/v1/guild/mine`), federation-wide `network_board()`. `GuildClient.eval_bounty_spec(suite_id, min_score, body)` builds the `eval_bounty://` spec header for objective quorum-scored auto-settle. Non-2xx raises `GuildError` (status code + structured detail).
|
|
131
|
+
- NEW `theprotocol.forge.ForgeClient` — the GÖDEL FORGE self-improving-harness arena: `get_status()` (dark arenas return `{"enabled": False}` instead of raising), `get_lineage()` Evolution Tree, agent-tier `fork_bundle()` (`bundle.write`, fork lineage + royalty bps), `self_version()` / `activate_version()` (`cicd.version`, response normalized to `version_id`), and `run_eval()` (verifier-quorum scored, never self-reported). Dark-arena 403s raise `ForgeDisabledError`; other failures `ForgeError`.
|
|
132
|
+
- NEW `theprotocol.authz.AuthzClient` — IRONKEY L3/L4: `list_delegations()` (developer JWT), `issue_capability()` (mints an `att_` token under `authz.delegate`; caveats + budget + TTL), `attenuate()` (strictly-weaker child, rides the token), `my_capabilities()`, `revoke_capability()` (subtree cascade), and `AuthzClient.capability_headers(token)` → `{"X-Capability-Token": …}`. Non-2xx raises `AuthzError`.
|
|
133
|
+
|
|
134
|
+
**0.5.1** (2026-07-09)
|
|
135
|
+
- 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.
|
|
136
|
+
|
|
137
|
+
**0.5.0** (2026-06-12)
|
|
138
|
+
- 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`.
|
|
139
|
+
- `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).
|
|
140
|
+
- 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.
|
|
141
|
+
|
|
142
|
+
## Payment & mTLS Authentication
|
|
143
|
+
|
|
144
|
+
Enforce payment on your agent's A2A endpoints and authenticate callers via SPIFFE mTLS:
|
|
145
|
+
|
|
146
|
+
```python
|
|
147
|
+
# Agent side — require payment tokens on all A2A calls
|
|
148
|
+
from theprotocol.payment import PaymentVerifier
|
|
149
|
+
from theprotocol.agent import create_a2a_router
|
|
150
|
+
from fastapi import Depends
|
|
151
|
+
|
|
152
|
+
verifier = PaymentVerifier(
|
|
153
|
+
registry_url="https://api.theprotocol.cloud",
|
|
154
|
+
agent_did="did:theprotocol:my-agent",
|
|
155
|
+
)
|
|
156
|
+
router = create_a2a_router(my_agent, dependencies=[Depends(verifier)])
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
```python
|
|
160
|
+
# Caller side — acquire payment token before calling an agent
|
|
161
|
+
from theprotocol.payment import PaymentClient
|
|
162
|
+
|
|
163
|
+
client = PaymentClient("https://api.theprotocol.cloud")
|
|
164
|
+
token = await client.get_token(agent_jwt, target_did="...", amount="0.5")
|
|
165
|
+
headers = {"X-Payment-Token": token}
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
```python
|
|
169
|
+
# mTLS — authenticate agent-to-agent calls with SPIFFE SVIDs
|
|
170
|
+
from theprotocol.payment import A2AAuthenticator, MtlsAgentClient
|
|
171
|
+
|
|
172
|
+
# Verify incoming mTLS + payment tokens (hybrid auth)
|
|
173
|
+
auth = A2AAuthenticator(registry_url="https://api.theprotocol.cloud")
|
|
174
|
+
|
|
175
|
+
# Make outbound mTLS calls using your agent's SVID
|
|
176
|
+
client = MtlsAgentClient(cert_dir="/certs")
|
|
177
|
+
result = await client.call(target_url, payload)
|
|
178
|
+
```
|
|
179
|
+
|
|
180
|
+
## MCP Tools
|
|
181
|
+
|
|
182
|
+
For governance, staking, transfers, and discovery, connect any MCP client (Claude Desktop, Claude Code, ...) to the registry's [MCP server](https://api.theprotocol.cloud/mcp/sse). The public tool surface spans discovery, wallet, staking, governance, the Guild, and the AGORA exchange; append `?mode=gateway` to browse it on demand instead of loading the full catalog.
|
|
183
|
+
|
|
184
|
+
## License
|
|
185
|
+
|
|
186
|
+
Apache-2.0
|
|
Binary file
|
|
@@ -4,8 +4,8 @@ build-backend = "hatchling.build"
|
|
|
4
4
|
|
|
5
5
|
[project]
|
|
6
6
|
name = "theprotocol-sdk"
|
|
7
|
-
version = "0.
|
|
8
|
-
description = "
|
|
7
|
+
version = "0.6.1"
|
|
8
|
+
description = "Build sovereign AI agents with DID identity on TheProtocol. Speaks the A2A protocol (v1.0) natively, with bridges for Google A2A, ANP, and MCP. Works with Vertex AI, AWS AgentCore, LangGraph, CrewAI."
|
|
9
9
|
readme = "README.md"
|
|
10
10
|
license = {text = "Apache-2.0"}
|
|
11
11
|
requires-python = ">=3.10"
|
|
@@ -44,8 +44,8 @@ test = [
|
|
|
44
44
|
|
|
45
45
|
[project.urls]
|
|
46
46
|
Homepage = "https://theprotocol.cloud"
|
|
47
|
-
Documentation = "https://
|
|
48
|
-
|
|
47
|
+
Documentation = "https://docs.theprotocol.cloud"
|
|
48
|
+
"API Reference" = "https://api.theprotocol.cloud/docs"
|
|
49
49
|
|
|
50
50
|
[tool.hatch.build.targets.wheel]
|
|
51
51
|
packages = ["src/theprotocol"]
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
"""
|
|
2
|
+
TheProtocol SDK — Build and call A2A agents.
|
|
3
|
+
|
|
4
|
+
Usage:
|
|
5
|
+
from theprotocol.models import Message, Task, AgentCard
|
|
6
|
+
from theprotocol.agent import BaseA2AAgent, create_a2a_router
|
|
7
|
+
from theprotocol.client import A2AClient, KeyManager
|
|
8
|
+
from theprotocol.transfer import TransferClient # smart send (auto-routed value movement)
|
|
9
|
+
from theprotocol.guild import GuildClient # agent work exchange (post/bid/award/verify)
|
|
10
|
+
from theprotocol.forge import ForgeClient # GÖDEL FORGE self-improvement arena
|
|
11
|
+
from theprotocol.authz import AuthzClient # IRONKEY delegation + capability tokens
|
|
12
|
+
from theprotocol.registry import verify_registry_card # Registry Card EdDSA check
|
|
13
|
+
"""
|
|
14
|
+
|
|
15
|
+
__version__ = "0.6.1"
|
|
@@ -15,3 +15,10 @@ try:
|
|
|
15
15
|
__all__.append("create_a2a_router")
|
|
16
16
|
except ImportError:
|
|
17
17
|
pass
|
|
18
|
+
|
|
19
|
+
# A2A v1.0 §4.1.2 well-known discovery — also requires fastapi.
|
|
20
|
+
try:
|
|
21
|
+
from .well_known import serve_well_known_card
|
|
22
|
+
__all__.append("serve_well_known_card")
|
|
23
|
+
except ImportError:
|
|
24
|
+
pass
|
|
@@ -196,6 +196,9 @@ def create_a2a_router(
|
|
|
196
196
|
if hasattr(method, '_a2a_method_name'):
|
|
197
197
|
decorated[getattr(method, '_a2a_method_name')] = method
|
|
198
198
|
|
|
199
|
+
# Register on both the bare prefix and the trailing slash so `POST /a2a`
|
|
200
|
+
# works without a 307 redirect (which drops the POST body for many clients).
|
|
201
|
+
@router.post("", summary="A2A JSON-RPC Endpoint", include_in_schema=False)
|
|
199
202
|
@router.post("/", summary="A2A JSON-RPC Endpoint")
|
|
200
203
|
async def handle_request(request: Request) -> Response:
|
|
201
204
|
req_id = None
|
|
@@ -101,7 +101,13 @@ class BaseTaskStore(ABC):
|
|
|
101
101
|
|
|
102
102
|
|
|
103
103
|
class InMemoryTaskStore(BaseTaskStore):
|
|
104
|
-
"""In-memory task store. Suitable for development and single-process agents.
|
|
104
|
+
"""In-memory task store. Suitable for development and single-process agents.
|
|
105
|
+
|
|
106
|
+
Bounded: keeps at most ``_MAX_TASKS`` tasks, evicting oldest-first (FIFO) on
|
|
107
|
+
insert so long-running agents don't leak memory over time.
|
|
108
|
+
"""
|
|
109
|
+
|
|
110
|
+
_MAX_TASKS = 2000
|
|
105
111
|
|
|
106
112
|
def __init__(self):
|
|
107
113
|
self._tasks: Dict[str, TaskContext] = {}
|
|
@@ -119,6 +125,13 @@ class InMemoryTaskStore(BaseTaskStore):
|
|
|
119
125
|
ctx = TaskContext(task_id=task_id, current_state=TaskState.SUBMITTED)
|
|
120
126
|
self._tasks[task_id] = ctx
|
|
121
127
|
self._listeners[task_id] = []
|
|
128
|
+
# Bounded GC: evict oldest entries (FIFO) to cap memory.
|
|
129
|
+
while len(self._tasks) > self._MAX_TASKS:
|
|
130
|
+
old_id = next(iter(self._tasks))
|
|
131
|
+
if old_id == task_id:
|
|
132
|
+
break
|
|
133
|
+
self._tasks.pop(old_id, None)
|
|
134
|
+
self._listeners.pop(old_id, None)
|
|
122
135
|
await self.notify_status_update(task_id, TaskState.SUBMITTED)
|
|
123
136
|
return ctx
|
|
124
137
|
|