Building Advanced Cybersecurity AI Agents with the CAI Framework

How to Build Advanced Cybersecurity AI Agents with CAI Using Tools, Guardrails, Handoffs, and Multi-Agent Workflows

The CAI Cybersecurity AI Framework enables the orchestration of modular agents to automate complex security tasks like reconnaissance and risk assessment. It allows developers to transform standard Python functions into executable tools for tasks like IP reputation checks and CVE lookups with a single decorator. This system supports multi-agent handoffs, ensuring specialized tasks are routed to the most appropriate AI model.

Why This Matters

Traditional security automation often relies on static scripts that lack the reasoning capabilities required for multi-step investigations or vulnerability deep-dives. By implementing agent-as-tool orchestration and multi-agent handoffs, engineers can build systems that dynamically adapt to threats while maintaining strict control via input guardrails. This approach addresses the technical reality of high-turn complexity in cybersecurity by allowing specialized agents to coordinate without losing state or context.

Key Insights

• The @function_tool decorator converts standard Python functions into callable tools within the CAI framework, enabling agents to simulate nmap-style port scans and check threat intelligence feeds.
• Hierarchical delegation via agent.as_tool() allow a Security Lead agent to consult specialized sub-agents, such as a CVE Expert, for technical vulnerability breakdowns.
• Input guardrails provide a heuristic defense layer to flag prompt injection attempts like ‘ignore previous instructions’ before the agent processes the request.
• Multi-turn context management is facilitated through result.to_input_list(), which carries prior messages forward to maintain awareness across iterative security queries.
• The CAI framework supports real-time streaming output using Runner.run_streamed() to provide immediate feedback during long-running security tasks or educational explanations.

Working Examples

Defining a custom cybersecurity tool and attaching it to a CAI agent for IP reputation lookups.

from cai.sdk.agents import Agent, Runner, OpenAIChatCompletionsModel, function_tool\n\n@function_tool\ndef check_ip_reputation(ip_address: str) -> str:\n    bad_ips = {"192.168.1.100", "10.0.0.99", "203.0.113.42"}\n    if ip_address in bad_ips:\n        return f"Warning: {ip_address} is MALICIOUS."\n    return f"Clean: {ip_address} is safe."\n\nrecon_agent = Agent(\n    name="Recon Agent",\n    instructions="You are a reconnaissance specialist. Use tools to investigate targets.",\n    tools=[check_ip_reputation],\n    model=OpenAIChatCompletionsModel(model="openai/gpt-4o-mini")\n)\n\nr = await Runner.run(recon_agent, "Check 10.0.0.99")

Implementing heuristic input guardrails to prevent prompt injection attacks.

async def detect_prompt_injection(ctx, agent, input_text) -> GuardrailFunctionOutput:\n    suspicious = ["ignore previous instructions", "system prompt override"]\n    for pattern in suspicious:\n        if pattern in input_text.lower():\n            return GuardrailFunctionOutput(tripwire_triggered=True)\n    return GuardrailFunctionOutput(tripwire_triggered=False)\n\nguarded_agent = Agent(\n    name="Guarded Agent",\n    input_guardrails=[InputGuardrail(guardrail_function=detect_prompt_injection)]\n)

Practical Applications

• Use Case: Automated CTF solving using a three-agent pipeline (Recon, Exploit, Validator) to identify attack vectors, decode data, and submit flags. Pitfall: High turn-count configurations without termination logic can lead to excessive token usage in failed exploit attempts.
• Use Case: Dynamic cryptographic hashing for file integrity verification using FunctionTool to generate MD5/SHA-256 hashes at runtime. Pitfall: Granting agents unvalidated access to internal libraries can lead to unintended side effects if the input schemas are not strictly enforced.

References:

• https://aliasrobotics.github.io/cai/
• https://github.com/aliasrobotics/cai
• https://arxiv.org/pdf/2504.06017
• https://marktechpost.com/2026/03/29/how-to-build-advanced-cybersecurity-ai-agents-with-cai-using-tools-guardrails-handoffs-and-multi-agent-workflows/