Skip to main content
Use this guide when you maintain the instrumentation yourself. First install the Python SDK and create a connection. The generated setup prompt can adapt these same boundaries to your repository. This integration supports Python 3.10+ agents with synchronous call sites. Python MCP servers, asynchronous execution and response streaming are not supported.

Instrument your existing request handler

This fragment belongs inside your application. SYSTEM_PROMPT, TOOLS, raw_model_call, run_existing_agent, trusted_context and send_to_caller are your existing prompt, tool definitions, provider call, existing tool loop, authenticated context and response sink. Keep your real tool loop and add a guard at its dispatcher.
At the real tool dispatcher, call guard_tool_call() with the declared toolset/tool, parameters, trusted context and execution callback. Use the repository-specific generated prompt to fit that wrapper to your application’s dispatcher. A policy check only protects paths that honor its outcome. load_rippletide_env() does not override process environment variables. The SDK also accepts the app/manual RIPPLETIDE_API_KEY and RIPPLETIDE_AGENT_ID configuration. Never put a Platform key in the agent.

Capture and failure behavior

Runtime capture defaults to metadata. Prompt text is withheld unless its owner explicitly enables allow_content_export=True on register_prompts(). Choose RIPPLETIDE_CAPTURE_MODE=redacted or full deliberately; see Privacy & capture. For tool and response guards, an enforced BLOCK raises RippletidePolicyBlockedError before the callback. Observe-only WOULD_BLOCK permits it. Network errors, 5xx, rate limits and malformed/interrupted HTTP responses fail open. Deterministic 400/401/403/404 decision errors raise RippletidePolicyDecisionError; do not treat them as telemetry outages. For a declared result collection, guard_tool_result() requires explicit allow_result_export=True. The complete result is sent for transient evaluation, and your apply callback preserves the original response shape while delivering only the allowed items. See Result filtering for the contract and fallback behavior.

Verify a real run

Run a turn that uses a guarded tool and delivers a response. Check rippletide verify, then rippletide events --wait. The app must show the inventory, heartbeat, tool and turn evidence, and the response-delivery outcome in Traces. Recording only a model candidate does not prove delivery.