# What Is the Role of Python Agents in AI-Infra-Guard? Security Scanning Engine Explained

> Discover the vital role of Python agents in AI-Infra-Guard. Learn how this security scanning engine automates LLM service analysis, from collection to reporting.

- Repository: [Tencent/AI-Infra-Guard](https://github.com/tencent/AI-Infra-Guard)
- Tags: deep-dive
- Published: 2026-08-22

---

**The Python agents in AI-Infra-Guard serve as the core orchestration and scanning engine that automates security analysis of LLM-powered services through a three-stage pipeline involving information collection, parallel vulnerability detection, and structured report generation.**

The Tencent AI-Infra-Guard project delivers an open-source security framework specifically designed to assess the safety posture of AI agents and LLM-powered infrastructure. At the heart of this system lies a **Python-based agent framework** that executes automated security assessments against target services. These Python agents function as both orchestrators and workers, driving the entire vulnerability detection lifecycle while the Go backend handles UI coordination and persistence.

## Three-Stage Security Scanning Pipeline

The Python agents implement a sophisticated pipeline defined in [`agent_scan/core/agent.py`](https://github.com/Tencent/AI-Infra-Guard/blob/main/agent_scan/core/agent.py) that systematically analyzes AI service security postures.

### Stage 1 – Information Collection and Reconnaissance

The scanning process begins when the `Agent.scan` method initiates `ScanPipeline.execute_stage` with the *project_summary* prompt. This reconnaissance phase gathers critical target configuration details, exposed endpoints, and language-specific metadata to establish the attack surface baseline before vulnerability testing commences.

### Stage 2 – Parallel Vulnerability Detection

During the detection phase, the framework spawns lightweight **skill-workers** for every detection skill—such as data-leakage, tool-abuse, or web-exfiltration checks. The `ScanPipeline.run_parallel_detection` method orchestrates these workers under a semaphore to prevent rate-limit exhaustion, with each worker invoking `run_agent` using a *skill_runner* prompt. This parallel architecture enables concurrent security testing without overwhelming target systems or API quotas.

### Stage 3 – Vulnerability Review and Taxonomy Mapping

The final stage invokes `ScanPipeline.execute_stage` once more, this time with the *agent_security_reviewer* prompt. This reviewer-agent consolidates `<vuln>` XML blocks discovered during detection, maps findings to the **OWASP ASI** (Agentic Security Intelligence) taxonomy, and assigns severity ratings to produce actionable, standardized intelligence.

## Core Architecture and Components

The Python agent subsystem comprises several specialized modules that coordinate LLM interactions and security testing logic.

### LLM Integration and Provider Configuration

The Python agents interact with LLM backends through the `agent_scan.utils.llm.LLM` class, which supports multiple providers including OpenAI and OpenRouter. The system consumes a provider configuration file ([`provider.yaml`](https://github.com/Tencent/AI-Infra-Guard/blob/main/provider.yaml)) via the `AIProviderClient` adapter to establish connections with live AI services, enabling dynamic switching between specialized LLMs for thinking, coding, and analysis tasks.

### Skill-Based Detection System

Security checks are implemented as reusable **skills** stored under `agent_scan/prompt/skills/*/`. Each skill contains a [`SKILL.md`](https://github.com/Tencent/AI-Infra-Guard/blob/main/SKILL.md) prompt file defining a specific security check—such as "web-exfiltration-detection" or "credential-leakage-scan". The framework dynamically discovers and executes these skills as parallel workers, allowing extensible security testing without modifying core agent code in [`agent_scan/core/agent.py`](https://github.com/Tencent/AI-Infra-Guard/blob/main/agent_scan/core/agent.py).

### Structured Report Generation

Upon completion, the agents generate **SARIF-compatible** reports through `generate_report_from_xml` implemented in [`agent_scan/core/report.py`](https://github.com/Tencent/AI-Infra-Guard/blob/main/agent_scan/core/report.py). These structured outputs can be consumed by the Go backend for persistence or exported as JSON for integration with external security information and event management systems.

## Practical Implementation Examples

### Command-Line Scanning

Execute standalone security scans using the CLI entry point defined in [`agent_scan/main.py`](https://github.com/Tencent/AI-Infra-Guard/blob/main/agent_scan/main.py):

```bash
aig-agent-scan --repo /path/to/project \
               --prompt "Focus on secret leakage" \
               --model gpt-4o-mini \
               --api_key $OPENAI_API_KEY \
               --language en \
               --output result.json

```

### Programmatic Agent Integration

Import the `Agent` class directly for custom automation workflows:

```python
import asyncio
from agent_scan.core.agent import Agent
from agent_scan.utils.llm import LLM

# Initialise the primary LLM (override with your own API key/model)

llm = LLM(model="gpt-4o-mini", api_key="YOUR_KEY", base_url="https://api.openai.com/v1")
agent = Agent(llm=llm, language="en", agent_provider="providers.yaml")

async def run():
    report = await agent.scan(repo_dir="/path/to/project", prompt="Check for credential leakage")
    print(report["language"], report["summary"])

asyncio.run(run())

```

### Custom Detection Skill Development

Extend the framework by creating new detection capabilities under `agent_scan/prompt/skills/`:

```bash

# Create a custom skill folder with SKILL.md, then invoke:

aig-agent-scan --repo . --skills my-custom-check

```

The framework automatically discovers the skill via the `skills` argument and executes it as a parallel worker alongside built-in checks.

## Summary

- The Python agents in AI-Infra-Guard implement a **three-stage pipeline** (reconnaissance, parallel detection, review) for automated security assessment of LLM services.
- The architecture centers on [`agent_scan/core/agent.py`](https://github.com/Tencent/AI-Infra-Guard/blob/main/agent_scan/core/agent.py), where `Agent.scan` and `ScanPipeline` classes orchestrate concurrent skill execution.
- **Skill-based detection** allows modular security checks stored as prompts in `agent_scan/prompt/skills/*/SKILL.md`.
- The system generates **SARIF-compatible reports** via [`agent_scan/core/report.py`](https://github.com/Tencent/AI-Infra-Guard/blob/main/agent_scan/core/report.py) for integration with security workflows.
- Python agents handle the core scanning logic while the Go backend manages UI, WebSocket coordination, and data persistence.

## Frequently Asked Questions

### How do Python agents differ from the Go backend in AI-Infra-Guard?

The Python agents constitute the actual security scanning engine that performs vulnerability detection, LLM interaction, and report generation. The Go backend provides the user interface, WebSocket server for real-time communication, CLI coordination, and persistence layer. While Go handles orchestration and delivery, Python executes the core analytical work according to the source code architecture.

### Can Python agents in AI-Infra-Guard scan non-Python AI services?

Yes. The Python agents are language-agnostic regarding their targets. Through the `AIProviderClient` adapter and configurable [`provider.yaml`](https://github.com/Tencent/AI-Infra-Guard/blob/main/provider.yaml), they can assess any LLM-powered service regardless of the target's implementation language, analyzing exposed endpoints and behaviors rather than source code alone.

### What is the purpose of the semaphore in the parallel detection stage?

The semaphore in `ScanPipeline.run_parallel_detection` limits concurrent skill-worker execution to prevent rate-limit exhaustion on target services and LLM APIs. This throttling mechanism ensures responsible scanning that respects API quotas while maintaining efficiency through parallel processing.

### How does the agent framework map vulnerabilities to security standards?

During the review stage, the agent_security_reviewer prompt processes discovered `<vuln>` XML blocks and maps them to the OWASP ASI (Agentic Security Intelligence) taxonomy. This classification occurs in [`agent_scan/core/agent.py`](https://github.com/Tencent/AI-Infra-Guard/blob/main/agent_scan/core/agent.py) during the final `ScanPipeline.execute_stage` call, standardizing findings for security teams.