a2akit 0.0.1__tar.gz

a2akit-0.0.1/.github/workflows/ci.yml

@@ -0,0 +1,50 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with: { version: "latest" }
+      - run: uv python install 3.11
+      - run: uv sync --dev
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+
+  test:
+    name: Test (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v4
+        with: { version: "latest" }
+      - run: uv python install ${{ matrix.python-version }}
+      - run: uv sync --dev
+      - name: Run tests
+        run: |
+          uv run pytest \
+            --cov=a2akit \
+            --cov-report=term-missing \
+            --cov-report=xml:coverage.xml \
+            --cov-fail-under=90 \
+            --junitxml=results.xml
+      - name: Upload coverage
+        if: matrix.python-version == '3.11'
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-report
+          path: coverage.xml

a2akit-0.0.1/.github/workflows/publish.yml

@@ -0,0 +1,46 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+  id-token: write
+
+jobs:
+  publish:
+    name: Build & Publish
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verify tag matches pyproject.toml
+        run: |
+          TAG="${GITHUB_REF#refs/tags/v}"
+          PKG=$(grep -m1 '^version' pyproject.toml | sed 's/.*"\(.*\)"/\1/')
+          if [ "$TAG" != "$PKG" ]; then
+            echo "::error::Tag v$TAG does not match pyproject.toml version $PKG"
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v4
+        with: { version: "latest" }
+      - run: uv python install 3.11
+      - run: uv sync --dev
+
+      - name: Lint
+        run: uv run ruff check src/ tests/
+
+      - name: Test
+        run: uv run pytest --cov=a2akit --cov-fail-under=90
+
+      - name: Build
+        run: uv build
+
+      - name: Publish
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          packages-dir: dist/

a2akit-0.0.1/.gitignore

@@ -0,0 +1,11 @@
+.venv/
+__pycache__/
+*.pyc
+*.pyo
+*.egg-info/
+dist/
+build/
+.claude/
+.pytest_cache/
+.ruff_cache/
+.coverage

a2akit-0.0.1/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/).
+
+## [0.0.1] — 2025-XX-XX
+
+### Added
+- Initial release.
+- `A2AServer` with one-liner FastAPI setup.
+- `Worker` ABC with `TaskContext` for agent logic.
+- Full A2A v0.3.0 HTTP+JSON transport (REST endpoints).
+- Streaming via SSE (`message:stream`, `tasks:subscribe`).
+- Cooperative and force-cancel with timeout fallback.
+- Multi-turn support (`request_input`, `request_auth`).
+- Direct reply mode (`reply_directly`).
+- Artifact streaming with append semantics.
+- Context persistence (`load_context`, `update_context`).
+- `InMemoryStorage`, `InMemoryBroker`, `InMemoryEventBus`, `InMemoryCancelRegistry`.
+- Agent card discovery (`/.well-known/agent-card.json`).
+- Optimistic concurrency control on all storage writes.
+- Idempotent task creation via `messageId`.

a2akit-0.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Markus Lang
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

a2akit-0.0.1/PKG-INFO

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: a2akit
+Version: 0.0.1
+Summary: A2A agent framework in one import.
+Project-URL: Homepage, https://github.com/markuslang1987/a2akit
+Project-URL: Documentation, https://github.com/markuslang1987/a2akit#readme
+Project-URL: Repository, https://github.com/markuslang1987/a2akit
+Project-URL: Changelog, https://github.com/markuslang1987/a2akit/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/markuslang1987/a2akit/issues
+Author: Markus Lang
+License-Expression: MIT
+License-File: LICENSE
+Keywords: a2a,agent,agent-to-agent,async,framework
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: a2a-sdk<1,>=0.3
+Requires-Dist: anyio>=4.4
+Requires-Dist: fastapi>=0.110
+Requires-Dist: pydantic>=2.7
+Requires-Dist: sse-starlette>=2.0
+Requires-Dist: uvicorn[standard]>=0.29
+Provides-Extra: langgraph
+Requires-Dist: langgraph>=0.2.0; extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# a2akit
+
+[![PyPI](https://img.shields.io/pypi/v/a2akit)](https://pypi.org/project/a2akit/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/a2akit)](https://pypi.org/project/a2akit/)
+[![CI](https://github.com/markuslang1987/a2akit/actions/workflows/ci.yml/badge.svg)](https://github.com/markuslang1987/a2akit/actions)
+
+**A2A agent framework in one import.**
+
+Build [Agent-to-Agent (A2A)](https://google.github.io/A2A/) protocol
+agents with minimal boilerplate. Streaming, cancellation, multi-turn
+conversations, and artifact handling — batteries included.
+
+## Install
+
+```bash
+pip install a2akit
+```
+
+## Quick Start
+
+```python
+from a2akit import A2AServer, AgentCardConfig, TaskContext, Worker
+
+
+class EchoWorker(Worker):
+    async def handle(self, ctx: TaskContext) -> None:
+        await ctx.complete(f"Echo: {ctx.user_text}")
+
+
+server = A2AServer(
+    worker=EchoWorker(),
+    agent_card=AgentCardConfig(
+        name="Echo Agent",
+        description="Echoes your input back.",
+        version="0.1.0",
+    ),
+)
+app = server.as_fastapi_app()
+```
+
+Run it:
+
+```bash
+uvicorn my_agent:app --reload
+```
+
+Test it:
+
+```bash
+curl -X POST http://localhost:8000/v1/message:send \
+  -H "Content-Type: application/json" \
+  -d '{"message":{"role":"user","parts":[{"text":"hello"}],"messageId":"1"}}'
+```
+
+## Features
+
+- **One-liner setup** — `A2AServer` wires storage, broker, event bus, and endpoints
+- **Streaming** — word-by-word artifact streaming via SSE
+- **Cancellation** — cooperative and force-cancel with timeout fallback
+- **Multi-turn** — `request_input()` / `request_auth()` for conversational flows
+- **Direct reply** — `reply_directly()` for simple request/response without task tracking
+- **Pluggable backends** — swap in Redis, PostgreSQL, RabbitMQ (coming soon)
+- **Type-safe** — full type hints, `py.typed` marker, PEP 561 compliant
+
+## A2A Protocol Version
+
+a2akit implements [A2A v0.3.0](https://google.github.io/A2A/).
+
+## Roadmap
+
+Planned features for upcoming releases. Priorities may shift based on feedback.
+
+| Feature | Target |
+|---|---|
+| Task middleware / hooks | v0.1.0 |
+| Lifecycle hooks + dependency injection | v0.1.0 |
+| Documentation website | v0.1.0 |
+| Redis EventBus | v0.2.0 |
+| Redis Broker | v0.2.0 |
+| PostgreSQL Storage | v0.2.0 |
+| SQLite Storage | v0.2.0 |
+| Backend conformance test suite | v0.2.0 |
+| OpenTelemetry integration | v0.2.0 |
+| RabbitMQ Broker | v0.3.0+ |
+| JSON-RPC transport | v0.3.0+ |
+| gRPC transport | v0.4.0+ |
+
+This roadmap is subject to change.
+
+## License
+
+MIT

a2akit-0.0.1/README.md

@@ -0,0 +1,93 @@
+# a2akit
+
+[![PyPI](https://img.shields.io/pypi/v/a2akit)](https://pypi.org/project/a2akit/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python](https://img.shields.io/pypi/pyversions/a2akit)](https://pypi.org/project/a2akit/)
+[![CI](https://github.com/markuslang1987/a2akit/actions/workflows/ci.yml/badge.svg)](https://github.com/markuslang1987/a2akit/actions)
+
+**A2A agent framework in one import.**
+
+Build [Agent-to-Agent (A2A)](https://google.github.io/A2A/) protocol
+agents with minimal boilerplate. Streaming, cancellation, multi-turn
+conversations, and artifact handling — batteries included.
+
+## Install
+
+```bash
+pip install a2akit
+```
+
+## Quick Start
+
+```python
+from a2akit import A2AServer, AgentCardConfig, TaskContext, Worker
+
+
+class EchoWorker(Worker):
+    async def handle(self, ctx: TaskContext) -> None:
+        await ctx.complete(f"Echo: {ctx.user_text}")
+
+
+server = A2AServer(
+    worker=EchoWorker(),
+    agent_card=AgentCardConfig(
+        name="Echo Agent",
+        description="Echoes your input back.",
+        version="0.1.0",
+    ),
+)
+app = server.as_fastapi_app()
+```
+
+Run it:
+
+```bash
+uvicorn my_agent:app --reload
+```
+
+Test it:
+
+```bash
+curl -X POST http://localhost:8000/v1/message:send \
+  -H "Content-Type: application/json" \
+  -d '{"message":{"role":"user","parts":[{"text":"hello"}],"messageId":"1"}}'
+```
+
+## Features
+
+- **One-liner setup** — `A2AServer` wires storage, broker, event bus, and endpoints
+- **Streaming** — word-by-word artifact streaming via SSE
+- **Cancellation** — cooperative and force-cancel with timeout fallback
+- **Multi-turn** — `request_input()` / `request_auth()` for conversational flows
+- **Direct reply** — `reply_directly()` for simple request/response without task tracking
+- **Pluggable backends** — swap in Redis, PostgreSQL, RabbitMQ (coming soon)
+- **Type-safe** — full type hints, `py.typed` marker, PEP 561 compliant
+
+## A2A Protocol Version
+
+a2akit implements [A2A v0.3.0](https://google.github.io/A2A/).
+
+## Roadmap
+
+Planned features for upcoming releases. Priorities may shift based on feedback.
+
+| Feature | Target |
+|---|---|
+| Task middleware / hooks | v0.1.0 |
+| Lifecycle hooks + dependency injection | v0.1.0 |
+| Documentation website | v0.1.0 |
+| Redis EventBus | v0.2.0 |
+| Redis Broker | v0.2.0 |
+| PostgreSQL Storage | v0.2.0 |
+| SQLite Storage | v0.2.0 |
+| Backend conformance test suite | v0.2.0 |
+| OpenTelemetry integration | v0.2.0 |
+| RabbitMQ Broker | v0.3.0+ |
+| JSON-RPC transport | v0.3.0+ |
+| gRPC transport | v0.4.0+ |
+
+This roadmap is subject to change.
+
+## License
+
+MIT

a2akit-0.0.1/examples/echo.py

@@ -0,0 +1,20 @@
+"""Simple echo worker — returns the user's input back."""
+
+from a2akit import A2AServer, AgentCardConfig, TaskContext, Worker
+
+
+class EchoWorker(Worker):
+    """Echoes the user's message back as-is."""
+
+    async def handle(self, ctx: TaskContext) -> None:
+        """Echo the user text back."""
+        await ctx.complete(f"Echo: {ctx.user_text}")
+
+
+server = A2AServer(
+    worker=EchoWorker(),
+    agent_card=AgentCardConfig(
+        name="Echo", description="Echoes input", version="0.1.0"
+    ),
+)
+app = server.as_fastapi_app()

a2akit-0.0.1/examples/langgraph_worker.py

@@ -0,0 +1,90 @@
+"""LangGraph worker — runs a graph with custom streaming, no LLM needed."""
+
+import asyncio
+from typing import TypedDict
+
+from langgraph.config import get_stream_writer
+from langgraph.graph import END, START, StateGraph
+
+from a2akit import A2AServer, AgentCardConfig, TaskContext, Worker
+
+TOTAL = 10
+BROKEN = {4, 7}
+DELAY = 0.5
+
+
+class FileProcessingState(TypedDict):
+    """Empty state -- the graph communicates via custom stream events."""
+
+
+async def process_node(state: FileProcessingState):
+    """Simulate processing files, emitting progress via stream writer."""
+    writer = get_stream_writer()
+    succeeded = 0
+    failed = 0
+
+    for i in range(1, TOTAL + 1):
+        name = f"report_{i:03d}.csv"
+        await asyncio.sleep(DELAY)
+
+        if i in BROKEN:
+            failed += 1
+            writer({"type": "error", "file": name, "index": i, "total": TOTAL})
+        else:
+            succeeded += 1
+            writer({"type": "done", "file": name, "index": i, "total": TOTAL})
+
+    writer(
+        {"type": "summary", "succeeded": succeeded, "failed": failed, "total": TOTAL}
+    )
+    return {}
+
+
+graph = (
+    StateGraph(FileProcessingState)
+    .add_node("process", process_node)
+    .add_edge(START, "process")
+    .add_edge("process", END)
+    .compile()
+)
+
+
+class LangGraphWorker(Worker):
+    """Runs a LangGraph file-processing pipeline and streams results via A2A."""
+
+    async def handle(self, ctx: TaskContext) -> None:
+        """Execute the graph and forward custom stream events as A2A artifacts."""
+        await ctx.send_status("Starting file processing pipeline...")
+        lines: list[str] = []
+
+        async for _mode, chunk in graph.astream({}, stream_mode=["custom"]):
+            evt_type = chunk.get("type", "")
+
+            if evt_type == "done":
+                line = f"[{chunk['index']}/{chunk['total']}] {chunk['file']}"
+                lines.append(line)
+                await ctx.send_status(line)
+
+            elif evt_type == "error":
+                line = f"[{chunk['index']}/{chunk['total']}] {chunk['file']} - FAILED"
+                lines.append(line)
+                await ctx.send_status(line)
+
+            elif evt_type == "summary":
+                lines.append(
+                    f"Summary: {chunk['succeeded']}/{chunk['total']} succeeded, "
+                    f"{chunk['failed']} failed"
+                )
+
+        await ctx.complete("\n".join(lines))
+
+
+server = A2AServer(
+    worker=LangGraphWorker(),
+    agent_card=AgentCardConfig(
+        name="File Processor",
+        description="LangGraph pipeline that processes files with streaming status",
+        version="0.1.0",
+    ),
+)
+app = server.as_fastapi_app()

a2akit-0.0.1/examples/streaming.py

@@ -0,0 +1,35 @@
+"""Streaming worker — emits word-by-word artifacts with progress updates."""
+
+import asyncio
+
+from a2akit import A2AServer, AgentCardConfig, TaskContext, Worker
+
+
+class StreamingWorker(Worker):
+    """Streams the user's input back word by word."""
+
+    async def handle(self, ctx: TaskContext) -> None:
+        """Split user text into words and emit each as a streaming artifact chunk."""
+        words = ctx.user_text.split()
+        await ctx.send_status(f"Streaming {len(words)} words...")
+
+        for i, word in enumerate(words):
+            is_last = i == len(words) - 1
+            await ctx.emit_text_artifact(
+                text=word + ("" if is_last else " "),
+                artifact_id="stream",
+                append=(i > 0),
+                last_chunk=is_last,
+            )
+            await asyncio.sleep(0.1)
+
+        await ctx.complete()
+
+
+server = A2AServer(
+    worker=StreamingWorker(),
+    agent_card=AgentCardConfig(
+        name="Streamer", description="Word-by-word streaming", version="0.1.0"
+    ),
+)
+app = server.as_fastapi_app()

a2akit-0.0.1/pyproject.toml

@@ -0,0 +1,99 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "a2akit"
+version = "0.0.1"
+description = "A2A agent framework in one import."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [
+    { name = "Markus Lang" },
+]
+keywords = ["a2a", "agent", "agent-to-agent", "framework", "async"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: FastAPI",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "a2a-sdk>=0.3,<1",
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "sse-starlette>=2.0",
+    "anyio>=4.4",
+    "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+langgraph = ["langgraph>=0.2.0"]
+
+[project.urls]
+Homepage = "https://github.com/markuslang1987/a2akit"
+Documentation = "https://github.com/markuslang1987/a2akit#readme"
+Repository = "https://github.com/markuslang1987/a2akit"
+Changelog = "https://github.com/markuslang1987/a2akit/blob/main/CHANGELOG.md"
+Issues = "https://github.com/markuslang1987/a2akit/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0",
+    "pytest-asyncio>=0.24",
+    "pytest-cov>=5.0",
+    "httpx>=0.27",
+    "ruff>=0.8",
+    "asgi-lifespan>=2.1.0",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/a2akit"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths = ["tests"]
+addopts = [
+    "--strict-markers",
+    "--tb=short",
+    "-q",
+    "--cov=a2akit",
+    "--cov-report=term-missing",
+    "--cov-fail-under=90",
+]
+markers = [
+    "slow: Tests that take >2s",
+]
+
+[tool.ruff]
+target-version = "py311"
+line-length = 99
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = [
+    "F", "E", "W", "I", "N", "UP", "B", "A", "C4",
+    "SIM", "TCH", "RUF", "PT", "ASYNC", "T20", "PIE",
+    "RSE", "RET", "TID",
+]
+ignore = ["E501", "RET504", "SIM108"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**" = ["T20"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["a2akit"]
+
+[tool.ruff.lint.flake8-tidy-imports]
+ban-relative-imports = "all"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true

a2akit-0.0.1/src/a2akit/__init__.py

@@ -0,0 +1,56 @@
+"""a2akit — A2A agent framework in one import."""
+
+from a2akit.agent_card import AgentCardConfig, ExtensionConfig, SkillConfig
+from a2akit.broker import (
+    Broker,
+    CancelRegistry,
+    InMemoryBroker,
+    InMemoryCancelRegistry,
+)
+from a2akit.event_bus import EventBus, InMemoryEventBus
+from a2akit.event_emitter import DefaultEventEmitter, EventEmitter
+from a2akit.server import A2AServer
+from a2akit.storage import (
+    ArtifactWrite,
+    ContextMismatchError,
+    InMemoryStorage,
+    Storage,
+    TaskNotAcceptingMessagesError,
+    TaskNotCancelableError,
+    TaskNotFoundError,
+    TaskTerminalStateError,
+    UnsupportedOperationError,
+)
+from a2akit.storage.base import ListTasksQuery, ListTasksResult
+from a2akit.task_manager import TaskManager
+from a2akit.worker import FileInfo, TaskContext, Worker
+
+__all__ = [
+    "A2AServer",
+    "AgentCardConfig",
+    "ArtifactWrite",
+    "Broker",
+    "CancelRegistry",
+    "ContextMismatchError",
+    "DefaultEventEmitter",
+    "EventBus",
+    "EventEmitter",
+    "ExtensionConfig",
+    "FileInfo",
+    "InMemoryBroker",
+    "InMemoryCancelRegistry",
+    "InMemoryEventBus",
+    "InMemoryStorage",
+    "ListTasksQuery",
+    "ListTasksResult",
+    "SkillConfig",
+    "Storage",
+    "TaskContext",
+    "TaskManager",
+    "TaskNotAcceptingMessagesError",
+    "TaskNotCancelableError",
+    "TaskNotFoundError",
+    "TaskTerminalStateError",
+    "UnsupportedOperationError",
+    "Worker",
+]