Metadata-Version: 2.4
Name: arkclaw-sdk
Version: 0.1.0
Summary: ArkClaw Invoke SDK — a2a protocol client for any a2a-compliant agent runtime.
Author: ArkClaw Team
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: a2a,agent,agentkit,arkclaw,jsonrpc,sdk
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic>=2.5
Requires-Dist: tenacity<10.0,>=8.0
Requires-Dist: typing-extensions>=4.9
Provides-Extra: all
Requires-Dist: opentelemetry-api>=1.27.0; extra == 'all'
Requires-Dist: opentelemetry-semantic-conventions>=0.48b0; extra == 'all'
Requires-Dist: typer>=0.12.0; extra == 'all'
Provides-Extra: cli
Requires-Dist: typer>=0.12.0; extra == 'cli'
Provides-Extra: dev
Requires-Dist: mkdocs-material>=9.5.0; extra == 'dev'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'dev'
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: opentelemetry-api>=1.27.0; extra == 'dev'
Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'dev'
Requires-Dist: opentelemetry-semantic-conventions>=0.48b0; extra == 'dev'
Requires-Dist: pyright>=1.1.370; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: typer>=0.12.0; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.24.0; extra == 'docs'
Provides-Extra: otel
Requires-Dist: opentelemetry-api>=1.27.0; extra == 'otel'
Requires-Dist: opentelemetry-semantic-conventions>=0.48b0; extra == 'otel'
Description-Content-Type: text/markdown

# ArkClaw Invoke SDK

[![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![a2a](https://img.shields.io/badge/a2a%20protocol-v0.3-success)](https://a2a-protocol.org/v0.3.0/specification/)

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

ArkClaw is the client SDK for [a2a](https://a2a-protocol.org/), 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](https://opentelemetry.io/docs/specs/semconv/gen-ai/);
  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

```bash
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

```python
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

```bash
$ 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](https://arkclaw.example.com)
<!-- TODO(roman): replace placeholder URL once the docs hostname is decided. -->

Local docs are in [`docs/`](docs/) and built with `mkdocs build --strict`.

## Quick links

- [Quickstart](docs/quickstart.md) — five-minute first invoke
- [Credentials guide](docs/guides/credentials.md) — the four auth methods
- [Retry & Timeout guide](docs/guides/retry-and-timeout.md) — production tuning
- [Observability guide](docs/guides/observability.md) — wire up OpenTelemetry
- [Async vs Sync guide](docs/guides/async-vs-sync.md) — pick the right API
- [Deployment guide](docs/guides/deployment.md) — for platform teams + partners
- [Changelog](CHANGELOG.md)

## Development

```bash
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](LICENSE).
