Skip to main content

​
Agent Security API

The Agent Security API protects AI agents by validating tool calls before execution and detecting anomalous behavior patterns. Project Scoping: Agent profiles are scoped by project. For the Developer API, project_id is automatically extracted from your API key. For the Consumer API, project_id must be provided in the request body.

​
Why Agent Security?

AI agents with tool access can be exploited to:
  • Execute dangerous commands: Shell injection, file system manipulation
  • Escalate privileges: Accessing restricted resources
  • Exfiltrate data: Sending data to external endpoints
  • Behave erratically: Unusual patterns indicating compromise

​
Endpoints

​
Validate Tool Call

Validate a tool call before allowing execution. 
POST /api/v1/agent/validate-tool
Request Body 
{
  "agent_id": "agent-123",
  "tool_name": "write_file",
  "arguments": {
    "path": "/tmp/output.txt",
    "content": "Hello world"
  },
  "session_id": "session-456"
}
Note: For Developer API, project_id is automatically extracted from your API key. For Consumer API, include project_id in the request body. Response (Allowed) 
{
  "allowed": true,
  "risk_score": 0.2,
  "risk_level": "low",
  "reason": "Tool call approved",
  "warnings": [],
  "blocked_reasons": []
}
Response (Blocked) 
{
  "allowed": false,
  "risk_score": 0.95,
  "risk_level": "critical",
  "reason": "Dangerous command detected",
  "warnings": ["Shell injection pattern detected"],
  "blocked_reasons": [
    "Attempt to execute shell command",
    "Path traversal detected"
  ]
}

​
Get Agent Stats

Get statistics for a specific agent. 
GET /api/v1/agent/{agent_id}/stats
Response 
{
  "agent_id": "agent-123",
  "total_tool_calls": 1523,
  "blocked_calls": 12,
  "avg_risk_score": 0.15,
  "active_sessions": 3,
  "anomalies_detected": 2
}

​
SDK Usage

from promptguard import PromptGuard

pg = PromptGuard(api_key="pg_xxx")

# Validate before executing a tool
result = pg.agent.validate_tool(
    agent_id="my-agent",
    tool_name="execute_code",
    arguments={"code": "print('hello')"}
)

if result["allowed"]:
    # Safe to execute
    execute_tool(tool_name, arguments)
else:
    print(f"Blocked: {result['blocked_reasons']}")

​
Risk Levels

LevelScore RangeAction
safe0.0 - 0.2Allow
low0.2 - 0.4Allow with logging
medium0.4 - 0.6May require review
high0.6 - 0.8Block or require approval
critical0.8 - 1.0Always block

​
Blocked Tools (Default)

These tools are blocked by default:
  • execute_shell, run_command, bash, system
  • delete_file, rm, rmdir
  • kill_process, terminate
  • send_email, http_post (without approval)

​
Project Isolation

Agent profiles are isolated by project. This means:
  • The same agent_id in different projects will have separate behavioral profiles
  • Profiles persist across restarts (stored in database)
  • Each project maintains its own baseline for anomaly detection
Developer API: project_id is automatically extracted from your API key. Ensure your API key is associated with a project. Consumer API: Include project_id in your request body. You must have access to the specified project.

​
Best Practices

  1. Validate every tool call: Don’t skip validation for “safe” tools
  2. Use sessions: Group related calls for better behavior analysis
  3. Review anomalies: Investigate when anomaly_score is high
  4. Set up alerts: Monitor for patterns indicating compromise
  5. Use project-scoped API keys: Ensure your API keys are associated with projects for proper isolation