agentverse-sdk 0.1.0__tar.gz

agentverse_sdk-0.1.0/.gitignore

@@ -0,0 +1,41 @@
+# IDEs
+.idea/
+.DS_Store
+
+# Data
+*.sqlite*
+
+# Python Specific
+__pycache__
+*.py[cgo]
+*.egg-info/
+.venv/
+.pnpm-store/
+
+# docker secrets
+.env
+# but allow test env files
+!.env.test
+
+# Cursor personal (machine-specific, not shared)
+.cursor/rules/personal/
+.cursor/commands/personal/
+
+# vscode
+.vscode/
+.history/
+# misc
+.__untracked__
+
+# vagrant
+.vagrant/
+
+# AVCTL Build directory
+build/
+
+# Goreleaser build directory
+dist/
+
+# ignore old mailbox-app folder
+/ui/mailbox-app/# Lint fix verification
+*.code-workspace

agentverse_sdk-0.1.0/DEVELOPER.md

@@ -0,0 +1,430 @@
+# Agentverse SDK — Developer Guide
+
+## Package Info
+
+| | |
+|---|---|
+| **PyPI name** | `agentverse-sdk` |
+| **Location** | `agentverse-core/pkg/agentverse-sdk/` (migrated from `uAgents/uagents-core/uagents_core/agentverse/sdk/`) |
+| **Source package** | `agentverse_sdk` |
+| **Core dependency** | `uagents-core` (external PyPI package — provides identity, envelope, chat protocol types) |
+
+### Public API
+
+```python
+from agentverse_sdk.a2a import init        # A2A adapter
+from agentverse_sdk.langgraph import init  # LangGraph adapter
+```
+
+### Install
+
+```bash
+pip install agentverse-sdk[a2a]       # A2A adapter
+pip install agentverse-sdk[langgraph] # LangGraph adapter
+```
+
+For local development (from monorepo root):
+
+```bash
+pip install -e "pkg/agentverse-sdk[a2a,langgraph,dev]"
+```
+
+---
+
+## Objective
+
+Connect any AI agent framework to [Agentverse](https://agentverse.ai) with zero user-facing configuration beyond a single URI string. The SDK:
+
+1. **Registers** the agent with Agentverse on startup.
+2. **Receives** chat messages via a Starlette POST endpoint (`/av/chat`).
+3. **Delegates** work to the underlying framework (LangGraph, A2A, etc.).
+4. **Replies** with the framework's output, converted to the chat protocol.
+5. **Reports** lifecycle events (start/stop) and errors to the Agentverse Events API.
+
+The user's experience is: call `init("agentverse://...")` and the SDK handles everything else invisibly.
+
+---
+
+## Philosophy
+
+| Principle | Meaning |
+|-----------|---------|
+| **Silent by default** | The SDK never prints, raises, or disrupts the host application. Failures are reported to Agentverse and swallowed. |
+| **Graceful degradation** | If init fails, the underlying framework still runs unpatched. A broken SDK must never break the user's agent. |
+| **Single point of truth** | The agent URI encodes identity, Agentverse host, and optional log level. No env vars, config files, or scattered state. |
+| **Wrapper, not framework** | The SDK wraps — it doesn't own the event loop, server, or application lifecycle. It hooks into Starlette lifespans and routes. |
+| **Observability via events** | All errors, state transitions, and lifecycle signals are dispatched to Agentverse's Events API. Logging is developer-only (hidden unless `?log=LEVEL` is set on the URI). |
+
+---
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────┐
+│  User's Agent Application (LangGraph / A2A / ...)    │
+└────────────────────────┬─────────────────────────────┘
+                         │ wraps
+┌────────────────────────▼─────────────────────────────┐
+│  Adapter Module (langgraph/ or a2a/)                 │
+│  - init()          → parse URI, store _ctx           │
+│  - Application     → register, add /av/chat route    │
+│  - _chat()         → validate, ack, dispatch to bg   │
+│  - _process_bg()   → call framework, convert, reply  │
+└────────────────────────┬─────────────────────────────┘
+                         │ uses
+┌────────────────────────▼─────────────────────────────┐
+│  _common/                                            │
+│  - av.py       → HTTP transport (register, send)     │
+│  - events.py   → error handling decorators           │
+│  - starlette.py→ request parsing, lifespan wiring    │
+│  - types.py    → AgentUri, AgentContext, events       │
+│  - config.py   → shared constants                    │
+│  - logger.py   → dual-audience logging               │
+│  - helpers.py  → utc_now()                           │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## Invariants
+
+These must hold in every adapter. Violating any of them is a bug.
+
+1. **Init never raises.** URI parsing failure → `log_sdk` + return. Everything else → `handle_init_errors` (suppress + report).
+2. **`_ctx.agent is None` means init failed.** All downstream code must guard on this and fall through to unpatched behavior.
+3. **`_chat()` returns `200 {}` or raises `HTTPException`.** Validation failures (bad envelope, wrong target) raise `HTTPException` with an appropriate status code. Successful requests return `200 {}` immediately — all processing (ack, framework call, reply) happens in a `BackgroundTask`.
+4. **Every background error produces a reply.** The sender must always receive either a real reply or an error message — never silence. If sending the reply itself fails, push a `"user"` event instead (the sender cannot be reached, but the failure must still be visible on the agent dashboard).
+5. **Error handling is structural, not inline.** Decorators (`report_error_starlette`, `report_error_reply`) and context managers (`handle_init_errors`, `chat_error_on_fail`) own all error paths. Business logic never has bare try/except.
+6. **Error dispatch is self-guarded.** Any code that runs inside an `except` block and can itself fail must be wrapped in its own try/except. These are last-line-of-defense paths.
+7. **Content extraction is pure.** `content.py` modules raise on failure — they never catch, log, or dispatch. The calling decorator handles everything.
+8. **The user never sees SDK internals.** No prints, no stack traces, no log output unless developer logging is explicitly enabled.
+
+---
+
+## Request Processing Flow
+
+Both adapters follow the same pipeline. Framework-specific steps are marked.
+
+```
+Incoming POST /av/chat
+    │
+    ▼
+┌─ _chat() ──────────────────────────────────── @report_error_starlette ─┐
+│  1. Parse envelope from JSON body                                       │
+│  2. Verify envelope signature (if enabled)                              │
+│  3. Validate target address matches this agent                          │
+│  4. Deserialize into ChatMessage or ChatAcknowledgement                 │
+│  5. If ChatAcknowledgement → return 200 {} (no-op)                      │
+│  6. Return 200 {} with BackgroundTask → _process_bg()                   │
+└─────────────────────────────────────────────────────────────────────────┘
+    │
+    ▼
+┌─ _process_bg() ────────────────────────────── @report_error_reply ─────┐
+│  1. Send ChatAcknowledgement to sender                                  │
+│  2. If message is StartSessionContent only → return (no-op)             │
+│  3. Extract text from ChatMessage                                       │
+│  4. Call framework:                                                      │
+│     • LangGraph: POST /runs/wait via ASGI transport → single response   │
+│     • A2A: on_message_send_stream() → async event stream                │
+│  5. Convert framework output to list[AgentContent]:                      │
+│     • LangGraph: extract_ai_content(response_dict)                      │
+│     • A2A: extract_content(event) per event                             │
+│  6. If no content produced → substitute DEFAULT_EMPTY_RESPONSE_TEXT      │
+│  7. Send ChatMessage reply to sender                                    │
+└─────────────────────────────────────────────────────────────────────────┘
+```
+
+### Key Differences Between Adapters
+
+| Aspect | LangGraph | A2A |
+|--------|-----------|-----|
+| Framework call | Single HTTP POST via ASGI transport | Async generator (streaming events) |
+| Session handling | Maps session → LangGraph thread_id (uuid5 hash) | Maps session → A2A contextId |
+| Reply cadence | One reply per request | One reply per content-bearing event |
+| Empty fallback | In `_send_reply` via `content or [fallback]` | Triggered when `is_task_complete` and nothing was sent |
+| Registration timing | During lifespan startup (env vars not ready at build time) | During `__init__` (server env is ready) |
+
+---
+
+## Error Handling
+
+### The Decorator Stack
+
+```
+handle_init_errors(uri)         → sync context manager, init phase
+    catches → dispatches event → suppresses
+
+report_error_starlette(ctx)     → async decorator, HTTP handlers
+    catches → dispatches event → re-raises as HTTPException(500)
+    (HTTPException passes through unchanged for custom HTTP errors)
+
+report_error_reply(ctx)         → async decorator, background processors
+    catches ChatProcessingError → dispatches event → sends error reply
+    catches Exception           → dispatches event → sends generic error reply
+
+chat_error_on_fail(msg)         → async context manager, inside @report_error_reply
+    catches → raises ChatProcessingError (which the outer decorator handles)
+```
+
+### Error Flow Diagram
+
+```
+Business logic raises
+    │
+    ├── Inside chat_error_on_fail?
+    │       └── Wraps as ChatProcessingError(custom_msg) → bubbles up
+    │
+    ▼
+report_error_reply catches
+    │
+    ├── ChatProcessingError
+    │       ├── Has .exc? → dispatch exception event + send .reply_text to user
+    │       └── No .exc   → dispatch message event + send .reply_text to user
+    │
+    └── Any other Exception
+            └── dispatch exception event + send DEFAULT_ERROR_REPLY to user
+```
+
+### `chat_error_on_fail` Categories
+
+| Usage | `category` | `include_exc` | Rationale |
+|-------|-----------|---------------|-----------|
+| Sending ack/reply (network) | `"user"` | `False` | Network failures aren't system bugs; don't attach traceback to event |
+| Parsing/extracting content | `"system"` | `True` (default) | SDK code failed; full traceback needed for debugging |
+
+---
+
+## Common Helpers Reference
+
+### `av.py` — Agentverse Transport
+
+| Function | Purpose |
+|----------|---------|
+| `generate_agent_auth_token(identity)` | Create a signed attestation token valid for 2 minutes |
+| `register_to_agentverse_sync(request, headers, config)` | Sync HTTP POST to register agent. Raises on failure (caller catches). |
+| `send_message_to_agent(dest, msg, sender, ...)` | Resolve destination via Almanac, send envelope. Async. Raises on failure. |
+| `set_agent_status(identity, active, config)` | Report online/offline to Almanac. Async. |
+| `verify_envelope(envelope)` | Check signature. Returns False on any failure. User addresses always pass. |
+| `_post_data(url, data, ...)` | Async httpx POST. Raises on non-2xx. |
+| `_post_data_sync(url, data, ...)` | Sync requests POST. Raises on non-2xx. Used only for event dispatch. |
+
+### `events.py` — Error Handling Machinery
+
+| Symbol | Purpose |
+|--------|---------|
+| `handle_init_errors(uri)` | Context manager: catch → report → suppress. For init and build phases. |
+| `report_error(ctx, category, reraise)` | Base decorator: catch → dispatch event → optionally re-raise. |
+| `report_error_starlette(ctx)` | HTTP decorator: report_error(reraise=True) + convert to 500. |
+| `report_error_reply(ctx)` | Background decorator: catch → dispatch → send error reply to sender. |
+| `chat_error_on_fail(msg, category, include_exc)` | Context manager: catch → raise ChatProcessingError. Use inside @report_error_reply. |
+| `ChatProcessingError(msg, category, exc)` | Custom exception to control error reply text. Like HTTPException for background tasks. |
+| `dispatch_event(agent, events)` | Sync POST to `/v1/events`. Raises on failure. |
+| `dispatch_event_safe(agent, events)` | Same but swallows failures. Use in except blocks. |
+
+### `starlette.py` — HTTP Layer
+
+| Function | Purpose |
+|----------|---------|
+| `parse_chat_message_from_request(request, verify, address)` | Validate envelope + deserialize to ChatMessage or ChatAcknowledgement. Raises HTTPException on any failure. |
+| `setup_agent_status_lifespan(existing)` | Wrap an existing lifespan with start/stop status reporting. |
+| `set_app_state(app, state)` | Attach AgentStarletteState to `app.state.agent`. |
+
+### `types.py` — Core Data Types
+
+| Type | Role |
+|------|------|
+| `AgentUri` | Parsed URI: key, name, agentverse config, identity (cached). Frozen Pydantic model. |
+| `AgentOptions` | Runtime options (`verify_envelope`, `track_interactions`). Pydantic model. |
+| `AgentverseAgent` | Combines URI + profile + metadata + options. Pydantic model. |
+| `AgentContext` | Mutable runtime state (dataclass). Holds `agent: AgentverseAgent | None`. |
+| `AgentStarletteState` | Attached to app.state. Holds key + agentverse config. Dataclass with cached identity. |
+| `AgentBatchEvents` | Event payload for `/v1/events`. Factory methods: `from_exception()`, `from_message()`. |
+
+### `config.py` — Constants
+
+| Constant | Value | Purpose |
+|----------|-------|---------|
+| `DEFAULT_AGENTVERSE_CHAT_ENDPOINT` | `"/av/chat"` | Route path for incoming messages |
+| `DEFAULT_HTTP_REQUESTS_TIMEOUT` | `10` (seconds) | Timeout for outbound HTTP calls |
+| `AGENT_AUTH_TOKEN_VALIDITY` | `120` (seconds) | Token lifetime |
+| `DEFAULT_EMPTY_RESPONSE_TEXT` | `"Agent returned no response."` | Fallback when framework produces no content |
+
+By default, SDK agents register as **proxy agents** (`track_interactions=True` on `AgentOptions`): hub stores the chat URL as `redirect_url` and Almanac publishes `agentverse.proxy_endpoint`. Senders hit `/v2/agents/proxy/submit`, hub records `ProxyAgentInteractionEvent`, then redirects to the chat URL. Opt out with `AgentOptions(track_interactions=False)`.
+
+### `logger.py` — Logging
+
+| Symbol | Purpose |
+|--------|---------|
+| `logger` | Standard Python logger (`"agentverse-sdk"`). Level CRITICAL by default (hidden). |
+| `log_sdk(msg)` | Emits at level 99 (displays as WARNING). Always visible. Reserved for critical user-facing messages. |
+| `configure(level)` | Enables developer logging at the given level. Called when URI has `?log=DEBUG`. |
+
+---
+
+## Implementing a New Adapter
+
+Follow this checklist when adding support for a new framework:
+
+### 1. Module Structure
+
+```
+agentverse_sdk/your_framework/
+    __init__.py     # re-exports init(), Application class
+    _app.py         # init(), Application class
+    config.py       # Framework-specific constants (ports, URLs, timeouts)
+    content.py      # Framework output → list[AgentContent] conversion
+    profile.py      # Build RegistrationRequest from framework metadata
+```
+
+### 2. Required Components
+
+```python
+from dataclasses import dataclass
+from agentverse_sdk._common.types import AgentContext
+
+# If you need extra state beyond AgentContext.agent:
+@dataclass
+class YourFrameworkContext(AgentContext):
+    config: YourConfig | None = None
+
+_ctx = YourFrameworkContext()
+```
+
+### 3. `init(agent_uri_str, ...)` Function
+
+```python
+def init(agent: str, *, profile=None, metadata=None, disable_message_auth=False):
+    # 1. Parse URI (outside handle_init_errors — report malformed URI via log_sdk)
+    try:
+        uri = AgentUri.from_str(agent)
+    except Exception as e:
+        log_sdk(FAILED_INIT_ERROR_FORMAT.format(f"malformed agent URI: {e}"))
+        return
+
+    # 2. Configure logging if URI has ?log=LEVEL
+    if uri.log_level is not None:
+        configure(uri.log_level)
+
+    # 3. Everything else inside handle_init_errors (suppresses + reports)
+    with handle_init_errors(uri):
+        _ctx.agent = AgentverseAgent(uri=uri, profile=profile, ...)
+        _ctx.config = YourConfig(...)
+        # Framework-specific patching/instrumentation
+```
+
+### 4. Application Class Pattern
+
+```python
+class YourApplication:
+    def register(self):
+        # Build RegistrationRequest, call register_to_agentverse_sync
+        # Raises on failure — caller wraps in handle_init_errors
+        ...
+
+    def build(self) -> Starlette:
+        # Guard: if _ctx.agent is None or _ctx.config is None → return original app
+        # Wrap lifespan with setup_agent_status_lifespan
+        # Add POST /av/chat route → self._chat
+        # Attach AgentStarletteState via set_app_state
+        ...
+
+    @report_error_starlette(_ctx)
+    async def _chat(self, request: Request) -> Response:
+        # parse_chat_message_from_request → if ack, return 200
+        # return 200 with BackgroundTask → self._process_bg
+        ...
+
+    @report_error_reply(_ctx, "user")
+    async def _process_bg(self, env: Envelope, msg: ChatMessage):
+        # chat_error_on_fail("Failed to send ack") → send ack
+        # if StartSessionContent only → return
+        # chat_error_on_fail("Failed to parse...") → call framework + extract content
+        # chat_error_on_fail("Failed to send reply") → send reply (with empty fallback)
+        ...
+```
+
+### 5. Content Extraction (`content.py`)
+
+- **Input**: Framework-specific response (dict, event stream, etc.) + `agent_uri: AgentUri`
+- **Output**: `list[AgentContent]` (TextContent, ResourceContent)
+- **Async**: Content functions are async (storage upload requires it).
+- **Rules**:
+  - Raise on unrecoverable failure (the calling decorator handles it).
+  - Never drop data. Use data: URIs for binary, JSON serialization for structured data.
+  - Handle each content type with explicit isinstance/type checks.
+  - Return `[]` for genuinely empty responses (the adapter handles the fallback).
+  - For operations with graceful fallbacks (e.g. storage upload), use the `_safe`
+    variant of the helper (e.g. `upload_to_storage_safe`). The safe helper handles
+    logging and system event dispatch internally.
+
+---
+
+## Known Issues & Improvement Opportunities
+
+### Design Improvements to Consider
+
+1. **Extract common background processing** — Both adapters share identical logic for: send ack → check StartSession → [framework-specific] → send reply. The shared prefix/suffix could be a base class method or a helper function, with only the framework call as the varying step.
+
+2. **Testable Application classes** — Currently `_ctx` is a module-level global, making unit testing require module-level state manipulation. Consider accepting context as a constructor parameter (with module-level default) so tests can inject isolated state.
+
+3. **Content fallback in common** — Both adapters implement `content or [TextContent(text=DEFAULT_EMPTY_RESPONSE_TEXT)]` independently. This could be a shared `ensure_content(content: list[AgentContent]) -> list[AgentContent]` helper in common.
+
+4. **Rate limiting / backoff** — Event dispatch (`dispatch_event`) has no retry or backoff. If the Events API is temporarily down, events are silently lost. Consider a simple bounded queue with retry (similar to Sentry's telemetry buffer pattern).
+
+5. **Structured event metadata** — Currently errors are dispatched with just exception + traceback. Adding structured metadata (adapter name, framework version, message_id being processed) would improve Agentverse-side debugging.
+
+---
+
+## Logging & Events
+
+### Event Categories
+
+| Category | Audience | Dashboard visibility |
+|----------|----------|---------------------|
+| `"system"` | Agentverse/SDK developers only | Internal monitoring — users never see these |
+| `"user"` | End users | Visible on the user's agent dashboard |
+
+Three entities produce or are affected by errors:
+
+1. **System** — the Agentverse platform and SDK infrastructure.
+2. **User** — the agent developer using Agentverse services.
+3. **Sender** — external agents interacting with the user's agent.
+
+**Decision rule:** `"user"` events for anything related to the user or sender. Everything else is `"system"`.
+
+**Use `"system"` events for:** infrastructure degradation the SDK handles gracefully (storage upload failures, transient service errors) and SDK bugs. These let the Agentverse team detect problems without requiring users to share logs. Users never see these.
+
+**Use `"user"` events for:** errors caused by the user's own code (tool failures, unhandled exceptions in the framework) **and** errors originating from sender agents (malformed messages, invalid envelopes). Reporting sender-side errors gives the user a clear record of where the issue occurred, helping all parties diagnose problems faster.
+
+### Logging Channels
+
+| Audience | API | Visibility | Use for |
+|----------|-----|-----------|---------|
+| End user | `log_sdk(msg)` | Always visible (level 99) | Init errors only: URI parse failures, events API unreachable during init |
+| Developer | `logger.debug/info/error` | Hidden unless `?log=LEVEL` | Registration, sender addresses, dispatch outcomes |
+| Agentverse team | `dispatch_event_safe(uri, event, "system")` | Internal dashboard | Graceful degradations, service health signals |
+
+### Graceful Degradation Pattern
+
+When a non-critical operation fails but the SDK can continue with a fallback:
+
+```python
+except Exception as e:
+    logger.error("Storage upload failed: %s", e)
+    dispatch_event_safe(
+        agent_uri,
+        AgentBatchEvents.from_exception(e, "", "system"),
+    )
+    # proceed with fallback (e.g. data: URI)
+```
+
+This combination gives: developer logs for local debugging + system events for Agentverse-side monitoring — without requiring the user to do anything.
+
+**Never log:**
+- Raw Request objects (useless repr)
+- Info the ASGI server already prints (method, path, status)
+- Secrets, keys, or full URIs
+
+**Always log:**
+- What the SDK does that's invisible to the framework (registration, ack sent, reply dispatched)
+- Error context inside except blocks (but only at `error` level)

agentverse_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,50 @@
+Metadata-Version: 2.4
+Name: agentverse-sdk
+Version: 0.1.0
+Summary: Agentverse SDK — connect any AI agent framework to Agentverse
+Project-URL: homepage, https://fetch.ai
+Project-URL: repository, https://github.com/fetchai/agentverse
+Author-email: "Fetch.ai" <developer@fetch.ai>
+License: Apache 2.0
+Requires-Python: <4.0,>=3.10
+Requires-Dist: httpx<0.29.0,>=0.28.1
+Requires-Dist: pydantic<3.0,>=2.8
+Requires-Dist: requests<3.0,>=2.32.3
+Requires-Dist: starlette<1.0,>=0.37.0
+Requires-Dist: uagents-core<0.5.0,>=0.4.5
+Provides-Extra: a2a
+Requires-Dist: a2a-sdk<0.4.0,>=0.3.20; extra == 'a2a'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<1,>=0.24; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0; extra == 'dev'
+Requires-Dist: python-dotenv<2.0,>=1.0.0; extra == 'dev'
+Requires-Dist: ruff<0.12,>=0.11.0; extra == 'dev'
+Provides-Extra: langgraph
+Requires-Dist: langgraph-api<1.0,>=0.2.0; (python_version >= '3.11') and extra == 'langgraph'
+Requires-Dist: langgraph-cli<1.0,>=0.4.0; (python_version >= '3.11') and extra == 'langgraph'
+Requires-Dist: python-dotenv<2.0,>=1.0.0; (python_version >= '3.11') and extra == 'langgraph'
+Description-Content-Type: text/markdown
+
+# agentverse-sdk
+
+Connect any AI agent framework to [Agentverse](https://agentverse.ai) with a single `init()` call.
+
+## Installation
+
+```bash
+# For A2A agents
+pip install agentverse-sdk[a2a]
+
+# For LangGraph agents
+pip install agentverse-sdk[langgraph]
+```
+
+## Quick start
+
+```python
+from agentverse_sdk.a2a import init
+
+init("agentverse://your-agent-key@agentverse.ai/your-agent")
+```
+
+See [DEVELOPER.md](DEVELOPER.md) for architecture and adapter implementation guide.

agentverse_sdk-0.1.0/README.md

@@ -0,0 +1,23 @@
+# agentverse-sdk
+
+Connect any AI agent framework to [Agentverse](https://agentverse.ai) with a single `init()` call.
+
+## Installation
+
+```bash
+# For A2A agents
+pip install agentverse-sdk[a2a]
+
+# For LangGraph agents
+pip install agentverse-sdk[langgraph]
+```
+
+## Quick start
+
+```python
+from agentverse_sdk.a2a import init
+
+init("agentverse://your-agent-key@agentverse.ai/your-agent")
+```
+
+See [DEVELOPER.md](DEVELOPER.md) for architecture and adapter implementation guide.

agentverse_sdk-0.1.0/agentverse_sdk/__init__.py

@@ -0,0 +1,3 @@
+"""Agentverse SDK — connect any AI agent framework to Agentverse."""
+
+__version__ = "0.1.0"