Skip to content

ADK 的 Cisco AI Defense 插件

Supported in ADKPython

Cisco AI Defense 是一个企业级 AI 安全平台，提供运行时防护栏以防止提示词注入、数据泄漏和有害内容等威胁。ADK 插件 将这些防护栏直接集成到 ADK Runner 生命周期中：它会检查提示词、模型响应和工具调用，然后根据可配置的安全策略允许或阻止它们。

使用场景

  • 模型调用的运行时保护：在模型调用之前检查用户提示词，在生成之后检查模型输出，然后根据策略（monitor 或 enforce）允许或阻止。
  • 工具和 MCP 调用检查：在执行前检查工具调用请求，在执行后检查工具响应，并在 enforce 模式下使用清晰的元数据阻止不安全的工具行为。
  • 可审计的决策追踪和告警：捕获决策上下文（操作、严重程度、分类、request_id/event_id），并可选择触发 on_violation 回调以进行监控和事件响应。

先决条件

安装

pip install cisco-aidefense-google-adk

设置 AI_DEFENSE_API_KEY 环境变量（以及用于工具检查的 AI_DEFENSE_MCP_API_KEY）。

与智能体配合使用

快速入门

使用单行代码将 Cisco AI Defense 添加到任何 ADK 智能体：

from aidefense_google_adk import defend

agent = defend(agent, mode="enforce")

或者获取一个用于整个应用的插件：

from aidefense_google_adk import defend

plugin = defend(mode="enforce")
app = App(name="my_app", root_agent=agent, plugins=[plugin])

全局插件

使用 CiscoAIDefensePlugin 将检查全局应用于 Runner 中的所有智能体：

from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService

from aidefense_google_adk import CiscoAIDefensePlugin

agent = LlmAgent(
    model="gemini-flash-latest",
    name="assistant",
    instruction="你是一个有用的助手。",
)

app = App(
    name="my_app",
    root_agent=agent,
    plugins=[
        CiscoAIDefensePlugin(mode="enforce"),
    ],
)
runner = Runner(app=app, session_service=InMemorySessionService())

按智能体设置回调

使用 make_aidefense_callbacks 将检查集成到特定智能体：

from google.adk.agents import LlmAgent
from aidefense_google_adk import make_aidefense_callbacks

cbs = make_aidefense_callbacks(mode="enforce")

agent = LlmAgent(
    model="gemini-flash-latest",
    name="assistant",
    instruction="你是一个有用的助手。",
)
cbs.apply_to(agent)  # 连接所有 4 个回调

模式

该插件支持三种操作模式：

模式 行为
monitor 检查所有流量，记录违规，从不阻止（默认）
enforce 检查所有流量，阻止违反策略的请求/响应
off 完全跳过检查

模式可以全局设置或按通道设置：

CiscoAIDefensePlugin(
    mode="monitor",      # 两者的默认值
    llm_mode="enforce",  # 仅覆盖 LLM
    mcp_mode="off",      # 仅覆盖工具
)

违规回调

使用 on_violation 回调在 monitor 和 enforce 模式下接收每次违规的通知：

def handle_violation(result):
    print(f"违规：{result.action} / {result.severity}")

CiscoAIDefensePlugin(
    mode="monitor",
    on_violation=handle_violation,
)

重试和故障开放支持

对于具有指数退避的自动重试、故障开放/故障关闭语义以及结构化的 Decision 对象，请使用 AgentsecPlugin 变体：

from aidefense_google_adk import AgentsecPlugin

app = App(
    name="my_app",
    root_agent=agent,
    plugins=[
        AgentsecPlugin(
            mode="enforce",
            fail_open=True,
            retry_total=3,
            retry_backoff=0.5,
        ),
    ],
)

或者在智能体级别：

from aidefense_google_adk import make_agentsec_callbacks

cbs = make_agentsec_callbacks(mode="enforce", fail_open=True)
cbs.apply_to(agent)

其他资源