Metadata-Version: 2.4
Name: arkclaw-sdk
Version: 0.1.1
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/)

**English** | [简体中文](README.zh-CN.md)

Python client for [a2a v0.3](https://a2a-protocol.org/v0.3.0/specification/),
the open JSON-RPC protocol for invoking remote agents.

The SDK is framework-neutral: it implements the wire protocol and nothing
else. Any runtime that exposes an a2a endpoint (OpenClaw, VeADK, LangGraph,
Pydantic AI, or a custom server) works without adapter code.

## Installation

```bash
pip install arkclaw-sdk
```

Optional extras:

```bash
pip install "arkclaw-sdk[cli]"     # arkclaw command-line tool
pip install "arkclaw-sdk[otel]"    # OpenTelemetry tracing
pip install "arkclaw-sdk[all]"     # both
```

Requires Python 3.10 or later. Wire types are Pydantic v2 models; HTTP is
handled by httpx.

## Usage

```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())
```

A synchronous `Client` exposes the same interface for code that cannot use
asyncio. It shares the async implementation internally and also works when
called from inside an already-running event loop.

### Streaming

`invoke_stream` consumes the server's Server-Sent Events stream and yields
typed events (`Message`, `Task`, `TaskStatusUpdateEvent`,
`TaskArtifactUpdateEvent`):

```python
async for event in client.invoke_stream("Summarize this repository"):
    ...
```

Responses and streaming events are validated against the a2a v0.3 wire
format; `arkclaw test-agent` (below) runs the same checks against any
endpoint.

### Authentication

| Credential                   | Grant                                        |
| ---------------------------- | -------------------------------------------- |
| `APIKeyCredential`           | static API key                               |
| `OAuthJWTCredential`         | caller-managed bearer token                  |
| `ClientCredentials`          | OAuth 2.0 client credentials (RFC 6749 §4.4) |
| `AgentKitIdentityCredential` | OAuth 2.0 with refresh-token grant (RFC 6749 §6) |

`DefaultCredentialChain` resolves credentials from environment variables,
following the precedence model familiar from boto3.

For end-user (three-legged) login, `arkclaw.auth.AuthorizationCodeFlow`
implements the OAuth 2.0 authorization-code flow with PKCE (RFC 6749 §4.1,
RFC 7636) for integration into a BFF or web backend.

### Retries and timeouts

Retry behaviour is configured with `RetryConfig`. 429, 5xx and network
errors are retried with exponential backoff and jitter; authentication and
other 4xx errors are not. For streaming, only connection establishment is
retried: an open stream is never replayed, so the server cannot receive
duplicate tasks.

`TimeoutConfig` maps to httpx's four timeout phases (connect, read, write,
pool) and provides `long_running()` and `disabled()` factories.

### Tracing

With the `otel` extra installed, spans follow the [OpenTelemetry GenAI
semantic conventions](https://opentelemetry.io/docs/specs/semconv/gen-ai/).
Message content is not recorded unless explicitly enabled via environment
variable.

## Command-line tool

Installed with the `[cli]` extra:

```
arkclaw test-agent <endpoint>    run the a2a v0.3 compliance checks
arkclaw chat <endpoint>          interactive streaming chat
arkclaw login                    browser-based OAuth login (PKCE)
arkclaw whoami                   show the cached identity
arkclaw logout                   remove a cached profile
arkclaw config show|set|unset    manage ~/.arkclaw/credentials profiles
arkclaw version                  print the SDK version
```

Credentials resolve in order: the `--api-key` flag, the `ARKCLAW_API_KEY`
environment variable, then the named profile in `~/.arkclaw/credentials`.

## Documentation

- [Getting started](docs/getting-started.md)
- [Quickstart](docs/quickstart.md)
- [Credentials](docs/guides/credentials.md)
- [Retries and timeouts](docs/guides/retry-and-timeout.md)
- [Observability](docs/guides/observability.md)
- [Async vs sync](docs/guides/async-vs-sync.md)
- [Deployment](docs/guides/deployment.md)
- [Changelog](CHANGELOG.md)

The documentation site is built from [`docs/`](docs/) with
`mkdocs build --strict`.

## Development

```bash
pip install -e ".[dev]"

pytest
ruff check src/ tests/
mypy --strict src/arkclaw
pyright src/arkclaw
mkdocs build --strict
```

## License

Apache 2.0. See [LICENSE](LICENSE).
