blockwatch 0.1.3

Lightweight telemetry for multi-agent collaboration and orchestration

BlockWatch Python SDK

Agentic Trust Authority — instrument multi-agent handoffs, detect runtime failures (loops, leaks, token burn), and stream session telemetry to BlockWatch without blocking your agents.

Install

pip install blockwatch          # core telemetry (requests)
pip install blockwatch[bedrock] # adds boto3 for framework="bedrock"

Install the agent framework you use in the same environment (langgraph, crewai, boto3, etc.). BlockWatch does not pull them in automatically except via [bedrock].

Quick start (Bedrock)

pip install blockwatch[bedrock]

import os
import blockwatch
import boto3

blockwatch.init(
    api_key=os.environ["BLOCKWATCH_API_KEY"],
    framework="bedrock",
)

client = boto3.client("bedrock-agent-runtime", region_name="us-east-1")

response = client.invoke_agent(
    agentId=os.environ["BEDROCK_AGENT_ID"],
    agentAliasId=os.environ["BEDROCK_AGENT_ALIAS_ID"],
    sessionId="your-session-id",
    inputText="Hello",
)

for event in response.get("completion", []):
    if "chunk" in event:
        print(event["chunk"]["bytes"].decode(), end="")

Call init() once, before creating the Bedrock client. enableTrace=True is injected automatically for bedrock-agent-runtime.

Copy .env.example for local runs. Runnable samples: examples/ (Bedrock, LangGraph, CrewAI).

Core pillars

Pillar	What BlockWatch does
Privacy	Captures Bedrock orchestration trace events (not raw app logs). Review what your traces contain before production; client-side field masking is on the roadmap.
Efficiency	Surfaces loops, leaks, and stuck handoffs on the BlockWatch platform. The SDK batches up to 50 events or 1 second per upload.
Cost	Correlates token usage and burn patterns from trace analytics so you can spot runaway agents early.

Framework support

Framework	SDK status
Amazon Bedrock (bedrock-agent-runtime)	Supported — install blockwatch[bedrock] or boto3; patches invoke_agent + trace stream
LangGraph	Supported — pip install langgraph in your app env; patches invoke / stream (prefer streaming for handoff data)
CrewAI	Supported — pip install crewai in your app env; patches Crew.kickoff
AutoGen	Telemetry worker only; entry-point patches coming later

See ROADMAP.md for parity tiers and backend normalization.

LangGraph

import os
import blockwatch

blockwatch.init(api_key=os.environ["BLOCKWATCH_API_KEY"], framework="langgraph")

# Call init before compile(); prefer stream() for step-level telemetry.
for chunk in compiled.stream(input, stream_mode="updates"):
    ...

How it works

• Background daemon thread gzip-batches JSON to https://api.blockwatch.ai/telemetry
• Short HTTP timeouts (connect 2s, read 5s) — network issues never crash your agent
• API key sent via X-BlockWatch-Api-Key header (not query strings)
• atexit best-effort flush (2s budget) on process exit

AWS Lambda

requirements.txt

blockwatch[bedrock]>=0.1.3

import os
import blockwatch

blockwatch.init(
    api_key=os.environ["BLOCKWATCH_API_KEY"],
    framework="bedrock",
)

Build the layer on Amazon Linux:

pip install -r requirements.txt -t python/

API

Function	Description
blockwatch.init(api_key, framework)	Start telemetry. framework: bedrock, langgraph, crewai, or autogen.

Requirements

• Python 3.9+
• Core dependency: requests (always installed with blockwatch)
• Bedrock: boto3 via pip install blockwatch[bedrock] or pip install boto3
• LangGraph / CrewAI: install those packages in your app environment when using those frameworks

Contributing

1. Open an issue or pull request.
2. Do not commit API keys, PyPI tokens, or customer IDs — use environment variables only.
3. Integration tests (optional): pytest tests/ -m integration with BLOCKWATCH_API_KEY, BEDROCK_AGENT_ID, and BEDROCK_AGENT_ALIAS_ID set.

Security

Report vulnerabilities via GitHub Security Advisories (preferred) or a private channel to your BlockWatch contact. Rotate any key that may have been exposed in logs or commits.

License

MIT — see LICENSE. Copyright (c) 2026 INNOGINE.