diff --git a/docs/integrations/assets/cisco-ai-defense.png b/docs/integrations/assets/cisco-ai-defense.png new file mode 100644 index 0000000000..5425016436 Binary files /dev/null and b/docs/integrations/assets/cisco-ai-defense.png differ diff --git a/docs/integrations/cisco-ai-defense.md b/docs/integrations/cisco-ai-defense.md new file mode 100644 index 0000000000..c088019077 --- /dev/null +++ b/docs/integrations/cisco-ai-defense.md @@ -0,0 +1,189 @@ +--- +catalog_title: Cisco AI Defense +catalog_description: Security guardrails to monitor or block agent prompts and tool calls +catalog_icon: /integrations/assets/cisco-ai-defense.png +--- + +# Cisco AI Defense plugin for ADK + +
+ Supported in ADKPython +
+ +[Cisco AI +Defense](https://www.cisco.com/site/us/en/products/security/ai-defense/index.html) +is an enterprise AI security platform that provides runtime guardrails to +protect against threats like prompt injection, data leakage, and harmful +content. The [ADK +plugin](https://github.com/cisco-ai-defense/ai-defense-google-adk) integrates +these guardrails directly into the ADK Runner lifecycle: it inspects prompts, +model responses, and tool calls, then allows or blocks them based on configurable +security policies. + +## Use cases + +- **Runtime protection for model calls**: Inspect user prompts before model + calls and model outputs after generation, then allow or block based on policy + (`monitor` or `enforce`). +- **Tool and MCP call inspection**: Inspect tool call requests before execution + and tool responses after execution, and block unsafe tool behavior in + `enforce` mode with clear metadata. +- **Auditable decision trace and alerts**: Capture decision context (action, + severity, classifications, request_id/event_id) and optionally trigger an + `on_violation` callback for monitoring and incident response. + +## Prerequisites + +- [Cisco AI Defense](https://www.cisco.com/site/us/en/products/security/ai-defense/index.html) account and API key +- Python >= 3.10 +- [ADK](https://adk.dev) >= 1.0.0 + +## Installation + +```bash +pip install cisco-aidefense-google-adk +``` + +Set the `AI_DEFENSE_API_KEY` environment variable (and `AI_DEFENSE_MCP_API_KEY` +for tool inspection). + +## Use with agent + +### Quickstart + +Add Cisco AI Defense to any ADK agent with a single line: + +```python +from aidefense_google_adk import defend + +agent = defend(agent, mode="enforce") +``` + +Or get a plugin for the entire app: + +```python +from aidefense_google_adk import defend + +plugin = defend(mode="enforce") +app = App(name="my_app", root_agent=agent, plugins=[plugin]) +``` + +### Global plugin + +Use `CiscoAIDefensePlugin` to apply inspection globally to all agents in a +Runner: + +```python +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="You are a helpful assistant.", +) + +app = App( + name="my_app", + root_agent=agent, + plugins=[ + CiscoAIDefensePlugin(mode="enforce"), + ], +) +runner = Runner(app=app, session_service=InMemorySessionService()) +``` + +### Per-agent callbacks + +Use `make_aidefense_callbacks` to wire inspection into a specific agent: + +```python +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="You are a helpful assistant.", +) +cbs.apply_to(agent) # wires all 4 callbacks +``` + +## Modes + +The plugin supports three operating modes: + +Mode | Behavior +---- | -------- +`monitor` | Inspect all traffic, log violations, never block (default) +`enforce` | Inspect all traffic, block requests/responses that violate policy +`off` | Skip inspection entirely + +Modes can be set globally or per-channel: + +```python +CiscoAIDefensePlugin( + mode="monitor", # default for both + llm_mode="enforce", # override for LLM only + mcp_mode="off", # override for tools only +) +``` + +## Violation callback + +Use the `on_violation` callback to receive notifications for every violation in +both `monitor` and `enforce` modes: + +```python +def handle_violation(result): + print(f"Violation: {result.action} / {result.severity}") + +CiscoAIDefensePlugin( + mode="monitor", + on_violation=handle_violation, +) +``` + +## Retry and fail-open support + +For automatic retry with exponential backoff, fail-open/fail-closed semantics, +and structured `Decision` objects, use the `AgentsecPlugin` variant: + +```python +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, + ), + ], +) +``` + +Or at the per-agent level: + +```python +from aidefense_google_adk import make_agentsec_callbacks + +cbs = make_agentsec_callbacks(mode="enforce", fail_open=True) +cbs.apply_to(agent) +``` + +## Additional resources + +- [GitHub Repository](https://github.com/cisco-ai-defense/ai-defense-google-adk) +- [PyPI Package](https://pypi.org/project/cisco-aidefense-google-adk/) +- [Cisco AI Defense](https://www.cisco.com/site/us/en/products/security/ai-defense/index.html) +- [cisco-aidefense-sdk on PyPI](https://pypi.org/project/cisco-aidefense-sdk/) diff --git a/docs/workflows/data-handling.md b/docs/workflows/data-handling.md index 8b43da1c21..0d8b2573f5 100644 --- a/docs/workflows/data-handling.md +++ b/docs/workflows/data-handling.md @@ -4,7 +4,7 @@ Supported in ADKPython v2.0.0Beta -Structuring and managing data between agents and graph-based notes is critical +Structuring and managing data between agents and graph-based nodes is critical for building reliable processes with ADK. This guide explains data handling within graph-based workflows and collaboration agents, including how information is transmitted and received between graph nodes using ***Events***. It covers