arkclaw-sdk 0.1.1

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

ArkClaw Invoke SDK

English | 简体中文

Python client for a2a v0.3, 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

pip install arkclaw-sdk

Optional extras:

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

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):

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. 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
• Quickstart
• Credentials
• Retries and timeouts
• Observability
• Async vs sync
• Deployment
• Changelog

The documentation site is built from docs/ with mkdocs build --strict.

Development

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.