dobby-collector 0.4.1

Telemetry collector for AI agents — stream runs, tools, LLM calls, and chains to the Dobby AI Control Plane for governance

dobby-collector

Telemetry collector for AI agents — stream runs, tools, LLM calls, and chains to the Dobby AI Control Plane for governance and compliance.

dobby-collector is the customer-side Python package for sending telemetry from any AI agent — LangChain, CrewAI, AutoGen, plain OpenAI/Anthropic SDKs, or custom code — to Dobby's governance plane. Every captured run gets evaluated by the Policy Scanner against your imported Compliance Packs (SOC 2, GDPR, EU AI Act, etc.) and surfaces violations in the Dobby dashboard.

Install

pip install dobby-collector

Quickstart

from dobby_collector import init, track, span, start_run, end_run

# 1. Initialize once at agent startup
init(
    api_key="dsdk_...",       # Generate at /dashboard/workloads/connect/python-sdk
    connector_id="wc_...",       # Same wizard hands you the connector ID
    framework="langchain",        # or 'crewai' | 'autogen' | omit to auto-detect
)

# 2. Decorate tool functions
@track(name="search_database", kind="tool")
def search_db(query: str) -> list:
    return db.execute(query)

# 3. Use spans for fine-grained capture
with span("retrieval", kind="tool", inputs={"query": "find AI startups"}):
    docs = retriever.invoke("find AI startups")

# 4. Wrap agent invocations in start/end_run
run = start_run(name="weekly_report", inputs={"week": "2026-W19"})
try:
    output = my_agent.run("Generate the weekly report")
    end_run(run, outputs={"report": output}, status="success")
except Exception as e:
    end_run(run, error=str(e), status="error")
    raise

The SDK runs a background thread that flushes events every 10 seconds (or immediately on terminal run.completed / run.failed events). Telemetry never blocks your agent — buffer overflow drops the oldest events silently.

What gets captured

What	When	Captured fields
Run boundaries	start_run / end_run	inputs, outputs, status, duration
Tool calls	@track(kind="tool") or span(kind="tool")	tool name, args, output, duration
LLM calls	LangChain auto-instrument (Phase 2b), or @track(kind="llm")	model, prompt, completion, tokens, latency
Custom spans	@track() / span()	name, inputs, outputs, duration

Config reference

init(
    api_key="dsdk_...",              # REQUIRED — or set DOBBY_API_KEY env var
    connector_id="wc_...",              # REQUIRED — or set DOBBY_CONNECTOR_ID env var
    base_url="https://dobby-ai.com",    # Override for self-hosted; or DOBBY_BASE_URL env
    flush_interval_seconds=10.0,        # How often the sender thread flushes
    max_buffer_events=10_000,           # Ring buffer cap (oldest dropped on overflow)
    framework="auto",                   # Hint or pin: 'langchain' | 'crewai' | 'autogen'
    host_fingerprint=None,              # Optional hostname/container ID for multi-replica
    pii_redact=False,                   # Opt-in: redact emails/SSNs/credit cards (Phase 2b)
    exclude_fields=[],                  # Fields to scrub from `data` payloads (Phase 2b)
)

Environment variables

The SDK reads these as fallbacks for init() args:

Env var	Default	Purpose
DOBBY_API_KEY	—	Connector bearer token (dsdk_*) — minted by the wizard
DOBBY_CONNECTOR_ID	—	Workload connector ID (wc_*)
DOBBY_BASE_URL	https://dobby-ai.com	Dobby control-plane URL

Set them in your deployment config and skip the corresponding init() args.

Lifecycle

from dobby_collector import init, shutdown

init(...)
# ... your agent runs ...
shutdown(timeout_seconds=5.0)  # Drains buffer + stops sender thread

shutdown() auto-fires via atexit if you forget, but call it explicitly when possible — atexit hooks have less time to drain before SIGTERM.

Status

Phase 2a (this release): Manual instrumentation API — init, track, span, start_run, end_run, shutdown. In-memory ring buffer + background sender + HTTP retries.

Phase 2b (next):

• LangChain auto-instrument via BaseCallbackHandler — zero code changes for LangChain agents
• DLQ to local SQLite — events survive network outages

Phase 4: CrewAI / AutoGen / OpenAI SDK / Anthropic SDK auto-instrument.

License

MIT — see LICENSE.

Runnable examples

Five end-to-end working agents you can python immediately after pip install. All make REAL LLM calls (no mocks) — substitute the model/tool for whatever your stack uses:

• examples/langchain_real_agent.py — LangChain ReAct agent with DuckDuckGo search, instrumented via DobbyCallbackHandler. Install: pip install dobby-collector[langchain].
• examples/crewai_real_agent.py — CrewAI sequential crew (Researcher + Writer) with optional web search tool, instrumented via DobbyCrewAIHandler. Requires crewai>=1.0. Install: pip install dobby-collector[crewai].
• examples/autogen_real_agent.py — AutoGen AssistantAgent (gpt-4o-mini) with a Python tool function, instrumented via DobbyAutoGenLogHandler. Requires autogen-core>=0.4. Install: pip install dobby-collector[autogen].
• examples/openai_assistants_real_agent.py — OpenAI Assistants API with a function tool, streamed through client.beta.threads.runs.stream() with DobbyAssistantsHandler. Install: pip install dobby-collector[openai_assistants].
• examples/manual_api_real_agent.py — Plain Python + OpenAI SDK + urllib, instrumented via manual @track / span / start_run API. Recommended for custom orchestration / OpenAI Responses API / any framework without a Dobby auto-handler yet.

All scripts call https://dobby-ai.com and produce real workload_runs + compliance_scans rows visible in the UI within ~60s.

Customer walkthrough

Step-by-step onboarding guide (10–15 min, written for non-Dobby engineers):

• docs/customer-onboarding/python-sdk-walkthrough.md

Covers: wizard navigation → install → run → verify in UI + 7 troubleshooting scenarios (auth errors / DLQ / proxies / serverless / PII redaction).

Links

• Full spec: docs/spikes/dobby-collector-sdk-spec.md
• Dobby AI Platform: dobby-ai.com
• Documentation: docs.dobby-ai.com/sdk/python-collector