From 1d7886a66a0ca470a4137d9f55e3c4019f00131f Mon Sep 17 00:00:00 2001 From: samueloladji-beep Date: Fri, 29 May 2026 01:28:38 -0700 Subject: [PATCH] docs: add Vaultak runtime security guide for AgentChat MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds python/docs/src/user-guide/agentchat-user-guide/vaultak-security.md — a guide for integrating Vaultak (pip install autogen-ext-vaultak) with AutoGen via the native DefaultInterventionHandler interface. The handler intercepts ToolCallRequestEvent messages before they reach agents, risk-scores the requested tool call (0–10), and returns DropMessage to block execution above a configurable threshold. PII is masked in ToolCallExecutionEvent outputs, and errors trigger dashboard alerts. Also adds a "Runtime Security (Vaultak)" grid card to index.md and registers vaultak-security in the Advanced toctree (after tracing). Co-Authored-By: Claude Sonnet 4.6 --- .../user-guide/agentchat-user-guide/index.md | 8 ++ .../agentchat-user-guide/vaultak-security.md | 136 ++++++++++++++++++ 2 files changed, 144 insertions(+) create mode 100644 python/docs/src/user-guide/agentchat-user-guide/vaultak-security.md diff --git a/python/docs/src/user-guide/agentchat-user-guide/index.md b/python/docs/src/user-guide/agentchat-user-guide/index.md index 016111df7a30..c5b02cd5b460 100644 --- a/python/docs/src/user-guide/agentchat-user-guide/index.md +++ b/python/docs/src/user-guide/agentchat-user-guide/index.md @@ -89,6 +89,13 @@ Add memory capabilities to your agents Log traces and internal messages ::: +:::{grid-item-card} {fas}`shield-halved;pst-color-primary` Runtime Security (Vaultak) +:link: ./vaultak-security.html +:link-alt: Runtime Security: Risk-score and block dangerous tool calls before they execute + +Risk-score and block dangerous tool calls before they execute +::: + :::{grid-item-card} {fas}`save;pst-color-primary` Serialize Components :link: ./serialize-components.html :link-alt: Serialize Components: Serialize and deserialize components @@ -150,6 +157,7 @@ memory logging serialize-components tracing +vaultak-security ``` diff --git a/python/docs/src/user-guide/agentchat-user-guide/vaultak-security.md b/python/docs/src/user-guide/agentchat-user-guide/vaultak-security.md new file mode 100644 index 000000000000..3b5d13d2df77 --- /dev/null +++ b/python/docs/src/user-guide/agentchat-user-guide/vaultak-security.md @@ -0,0 +1,136 @@ +# Runtime Security with Vaultak + +[Vaultak](https://vaultak.com) is a runtime security platform that adds real-time protection to +AutoGen agents. It intercepts every tool call and inter-agent message, scores risk on a 0–10 scale, +enforces your policy rules, masks PII in tool outputs, and blocks or drops dangerous actions before +they execute — with no changes to your existing agent or team logic. + +## Installation + +```bash +pip install autogen-ext-vaultak +``` + +Sign up at [vaultak.com](https://vaultak.com) to get your API key (starts with `vtk_`). + +## How It Works + +Vaultak integrates through AutoGen's native {py:class}`~autogen_core.DefaultInterventionHandler`. +The runtime calls the handler on every `on_send` and `on_publish` event _before_ the message +reaches its recipient. The Vaultak handler inspects {py:class}`~autogen_agentchat.messages.ToolCallRequestEvent` +messages, scores the requested tool call, and returns +{py:class}`~autogen_core.DropMessage` to block execution if the risk score exceeds your threshold. + +```{note} +{py:class}`~autogen_core.SingleThreadedAgentRuntime` is the only runtime that currently +supports intervention handlers. +``` + +## Quick Start + +```python +import asyncio +from autogen_agentchat.agents import AssistantAgent +from autogen_agentchat.teams import RoundRobinGroupChat +from autogen_agentchat.conditions import TextMentionTermination +from autogen_agentchat.ui import Console +from autogen_core import SingleThreadedAgentRuntime +from autogen_ext.models.openai import OpenAIChatCompletionClient +from autogen_ext_vaultak import VaultakInterventionHandler + + +async def main() -> None: + # Initialize the Vaultak handler + vaultak = VaultakInterventionHandler( + api_key="vtk_...", + agent_name="my-autogen-crew", + block_on_high_risk=True, + risk_threshold=7.0, + ) + + # Pass the handler to the runtime — every message is now monitored + runtime = SingleThreadedAgentRuntime( + intervention_handlers=[vaultak] + ) + runtime.start() + + model_client = OpenAIChatCompletionClient(model="gpt-4o") + + def search_web(query: str) -> str: + """Search the web for information.""" + return f"Results for: {query}" + + agent = AssistantAgent( + name="assistant", + model_client=model_client, + tools=[search_web], + ) + + termination = TextMentionTermination("TERMINATE") + team = RoundRobinGroupChat([agent], termination_condition=termination) + + await Console(team.run_stream(task="Research the latest AI safety developments.")) + await runtime.stop() + await model_client.close() + + +asyncio.run(main()) +``` + +## Configuration + +| Parameter | Type | Default | Description | +|---|---|---|---| +| `api_key` | `str` | — | Your Vaultak API key — required | +| `agent_name` | `str` | `"autogen-agent"` | Label for this runtime in the Vaultak dashboard | +| `block_on_high_risk` | `bool` | `True` | Drop messages whose risk score exceeds the threshold | +| `risk_threshold` | `float` | `7.0` | Score (0–10) above which tool calls are blocked | +| `verbose` | `bool` | `False` | Log every scored action to stdout | + +### Stricter threshold for sensitive workloads + +```python +vaultak = VaultakInterventionHandler( + api_key="vtk_...", + agent_name="prod-db-agent", + risk_threshold=5.0, # Block anything above medium risk +) +``` + +## What Gets Monitored + +| AutoGen event | Vaultak action | +|---|---| +| `ToolCallRequestEvent` published | Risk-scores the tool call (0–10); drops message if above threshold | +| `ToolCallRequestEvent` published | Checks tool call against your policy rules | +| `ToolCallExecutionEvent` received | Scans tool output for PII and masks it | +| Runtime `on_publish` / `on_send` | All messages pass through the handler | +| Exception / error message | Sends alert to your Vaultak dashboard | + +## Dashboard + +Every intercepted action is visible at [app.vaultak.com](https://app.vaultak.com): +real-time risk scores, full message history, policy violations, and alerts. +Policy rules can be configured there without changing your code. + +## Combining with OpenTelemetry Tracing + +Vaultak and AutoGen's built-in [OpenTelemetry tracing](tracing.ipynb) are fully compatible. +Use OTel for performance traces and distributed debugging; use Vaultak for security enforcement +and policy compliance. Pass both to the runtime: + +```python +from opentelemetry import trace + +runtime = SingleThreadedAgentRuntime( + tracer_provider=trace.get_tracer_provider(), # OTel tracing + intervention_handlers=[vaultak], # Vaultak security +) +``` + +## Links + +- [Vaultak documentation](https://docs.vaultak.com) +- [PyPI package](https://pypi.org/project/autogen-ext-vaultak) +- [GitHub](https://github.com/vaultak/autogen-ext-vaultak) +- [AutoGen InterventionHandler reference](../core-user-guide/framework/agent-and-agent-runtime.ipynb)