Suvra

Framework Integrations

Registration vs enforcement

The framework integration wrappers do not handle agent registration — they handle action-level enforcement after registration. Registration happens once, either at SDK init or via the /agents API.

When you instantiate Suvra(url=..., agent_id=...), the client auto-registers via PUT /agents/{agent_id}/register on first call and then heartbeats. agent_id is the only required field. Agents appear live in /dashboard/agents with last-seen timestamps.

from suvra import Suvra

guard = Suvra(
    url="http://your-suvra-server",
    agent_id="my-agent-001",          # REQUIRED
    agent_name="My Agent",
    framework="anthropic",
    purpose="Handles customer support queries",
    risk_tier="medium",
    tools_used=["web_search", "database_query"],
    data_classes_touched=["PII", "financial"],
    policy_id="policy-prod-001",
)

To pre-register from a deployment pipeline:

curl -X PUT https://suvra.example.com/agents/my-agent/register \
  -H "Content-Type: application/json" \
  -H "X-Suvra-Token: $SUVRA_AUTH_TOKEN" \
  -d '{
    "owner": "platform-team",
    "purpose": "Q4 report generator",
    "status": "active",
    "risk_tier": "medium",
    "approval_profile": "strict",
    "runtime_type": "python",
    "framework": "langchain"
  }'

See Agents for the full registration schema, env-var auto-resolution, and validation rules.

Framework adapters

Suvra ships thin framework adapters in suvra.integrations.*. Each adapter wraps the framework's native tool / callback surface so every tool call is validated against policy before it runs. All adapters use lazy imports — Suvra does not depend on framework packages at install time.

All examples below assume you have a Suvra client instantiated as shown above.

Claude Agent SDK (Anthropic)

from suvra.integrations.anthropic import suvra_hook, suvra_agent_options

hook = suvra_hook(suvra, fail_closed=True)
options = suvra_agent_options(suvra, fail_closed=True)
  • suvra_hook(suvra, *, fail_closed=False) — async PreToolUse hook. Rejects tool calls whose decision != allow. On Suvra errors, returns empty unless fail_closed=True.
  • suvra_agent_options(suvra, *, fail_closed=False) — convenience dict you can merge into ClaudeAgentOptions(...) so the hook is registered.

LangChain

from suvra.integrations.langchain import SuvraCallbackHandler, SuvraGuardRunnable

callbacks = [SuvraCallbackHandler(suvra, fail_closed=True)]
guarded = SuvraGuardRunnable(runnable, suvra, fail_closed=True)
  • SuvraCallbackHandler — a BaseCallbackHandler that intercepts on_tool_start and cancels tool execution on deny.
  • SuvraGuardRunnable — wraps any LangChain Runnable and validates the input payload as a Suvra action before invoke.

CrewAI

from suvra.integrations.crewai import suvra_before_tool_call, suvra_after_tool_call

crew = Crew(
    ...,
    before_tool_call=suvra_before_tool_call(suvra, fail_closed=True),
    after_tool_call=suvra_after_tool_call(suvra),
)
  • suvra_before_tool_call returns False to block a tool call; None to allow.
  • suvra_after_tool_call records the executed outcome for audit correlation.

AutoGen

from suvra.integrations.autogen import guard_tool, guard_function_map

@guard_tool(suvra, action_type="fs.write_file", fail_closed=True)
def write_report(path: str, content: str):
    ...

agent.register_function(guard_function_map(suvra, function_map, fail_closed=True))
  • guard_tool(suvra, action_type, *, fail_closed=False) — decorator that validates before each invocation. Builds action params from the function's bound arguments.
  • guard_function_map(suvra, function_map, *, fail_closed=False) — wraps every callable in an existing function_map with the same guard.

Google ADK

from suvra.integrations.google_adk import suvra_before_tool_call

agent = LlmAgent(
    ...,
    before_tool_callback=suvra_before_tool_call(suvra, fail_closed=True),
)

suvra_before_tool_call is an async ADK callback. It returns a dict (denial response) to short-circuit the tool call, or None to continue.

LlamaIndex

from suvra.integrations.llamaindex import guard_tools, SuvraToolWrapper

guarded = guard_tools(suvra, tools, fail_closed=True)
# or wrap a single tool:
guarded_tool = SuvraToolWrapper(tool, suvra, fail_closed=True)

Denied tool calls surface as a ToolOutput with an error payload, so the agent sees why the tool refused and can react.

OpenClaw

from suvra.integrations.openclaw import OpenClawGuard

guard = OpenClawGuard(suvra, default_actor="openclaw")
guard.execute(action)

OpenClawGuard wraps Suvra's execute flow with OpenClaw-specific actor defaults and action-id generation.

UiPath

from suvra.integrations.uipath import (
    SuvraGovernedRuntime,
    guard_process,
    guard_activity,
    suvra_guardrail_handler,
)

runtime = SuvraGovernedRuntime(suvra, fail_closed=True)

@guard_process(suvra, action_type="uipath.process.run", fail_closed=True)
def run_payroll(...): ...

@guard_activity(suvra, action_type="uipath.activity.http", fail_closed=True)
def post_invoice(...): ...
  • SuvraGovernedRuntime — async runtime wrapper that validates every invocation against policy.
  • guard_process / guard_activity — decorators for process-level and activity-level governance.
  • suvra_guardrail_handler — escalation handler for UiPath guardrail events.

Generic decorator

If your framework isn't listed, use the framework-agnostic decorator directly:

from suvra.sdk.decorators import guarded_tool

@guarded_tool(suvra, action_type="http.request", agent_id="my-agent")
def fetch(url: str):
    ...

Related