arkclaw-sdk 0.1.0

ArkClaw Invoke SDK — a2a protocol client for any a2a-compliant agent runtime.

ArkClaw Invoke SDK

Production-grade Python SDK for the a2a v0.3 agent-to-agent protocol.

ArkClaw is the client SDK for a2a, the open JSON-RPC protocol for invoking remote agents. The SDK does not bind to any agent framework — if a runtime exposes the a2a interface (OpenClaw / VeADK / LangGraph / Pydantic AI / a custom server), this SDK can drive it.

Features

• ✅ Full a2a v0.3 conformance, verified line-by-line against the canonical TypeScript spec at the v0.3.0 tag.
• ✅ Async + sync twin APIs (AsyncClient / Client) sharing one connection pool.
• ✅ Streaming via Server-Sent Events with a discriminated event union (Message | Task | TaskStatusUpdateEvent | TaskArtifactUpdateEvent).
• ✅ Four credential types: API key, OAuth JWT, AgentKit Identity (with RFC 6749 §6 refresh-token grant), Volcengine IAM v4 signing.
• ✅ Production retry with smart error classification, exponential backoff with jitter, and automatic re-signing per attempt (Volcengine rejects stale X-Date signatures).
• ✅ Multi-layer timeouts (connect / read / write / pool).
• ✅ OpenTelemetry tracing with GenAI semantic conventions; privacy-default off for message content (opt in via env var).
• ✅ CLI with arkclaw test-agent — a built-in a2a-v0.3 compliance checker for any endpoint.
• ✅ Type-safe: zero # type: ignore across the entire codebase. mypy --strict and pyright (strict mode) both clean.
• ✅ 313 acceptance tests, contract-first throughout development.

Install

pip install arkclaw-sdk           # core
pip install arkclaw-sdk[cli]      # + arkclaw command-line tool
pip install arkclaw-sdk[otel]     # + OpenTelemetry tracing
pip install arkclaw-sdk[all]      # cli + otel

Python ≥ 3.10 required.

30-second example

import asyncio
from arkclaw import AsyncClient, APIKeyCredential

async def main() -> None:
    async with AsyncClient(
        endpoint="https://my-agent.example.com/a2a/jsonrpc",
        credentials=APIKeyCredential(api_key="ark-..."),
    ) as client:
        result = await client.invoke("Hello, agent!")
        print(result.text)

asyncio.run(main())

CLI: validate a2a compliance

$ arkclaw test-agent https://my-agent.example.com/a2a/jsonrpc --api-key ark-...

Testing a2a v0.3 compliance for: https://my-agent.example.com/a2a/jsonrpc

[1/4] message/send round-trip                              ✓ OK
[2/4] Result envelope (Task | Message per §7.1)            ✓ OK
[3/4] Task.status nested (§6.1)                            ✓ OK
       └ status.state = 'completed'
[4/4] TaskState ∈ valid set (§6.3)                         ✓ OK

═══════════════════════════════════════════════
✓ Compliance: PASS (4/4 checks)
═══════════════════════════════════════════════

Documentation

→ arkclaw documentation site

Local docs are in docs/ and built with mkdocs build --strict.

Quick links

• Quickstart — five-minute first invoke
• Credentials guide — the four auth methods
• Retry & Timeout guide — production tuning
• Observability guide — wire up OpenTelemetry
• Async vs Sync guide — pick the right API
• Deployment guide — for platform teams + partners
• Changelog

Development

pip install -e ".[dev]"

pytest                                  # 313 acceptance tests
ruff check src/ tests/                  # lint
mypy --strict src/arkclaw               # types (zero errors)
pyright src/arkclaw                     # types (zero errors)
mkdocs build --strict                   # docs (zero warnings)

License

Apache 2.0 — see LICENSE.