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
}

Register Agent

POST /api/v1/agent/register

Request Body

{
  "agent_name": "billing-assistant",
  "allowed_tools": ["read_invoice", "send_summary"]
}

Response

{
  "agent_id": "agent-123",
  "agent_name": "billing-assistant",
  "agent_secret": "agsec_xxxxxxxx",
  "credential_prefix": "agsec_xxxx"
}

agent_secret is shown only once. Store it securely — it cannot be retrieved again, only rotated.

Rotate Agent Credential

Revoke the agent’s current credential and issue a new one.

POST /api/v1/agent/{agent_id}/rotate-credential

Response

{
  "agent_id": "agent-123",
  "new_secret": "agsec_yyyyyyyy",
  "credential_prefix": "agsec_yyyy",
  "old_credential_revoked": true
}

End Agent Session

End an agent session and clear its tracking data.

DELETE /api/v1/agent/{agent_id}/session/{session_id}

Agent Security Health

Health check for the agent security service. Useful for readiness probes before routing validation traffic.

GET /api/v1/agent/health

Get Managed Policy

Get the org-managed update policy for an enrolled device (used by the desktop agent to apply fleet-managed update settings).

GET /api/v1/agent/managed-policy

Response

{
  "fleet": true,
  "force_update_mode": "auto",
  "pinned_channel": "stable",
  "min_version_override": null
}

SDK Usage

Python
Node.js

from promptguard import PromptGuard

pg = PromptGuard(api_key="pg_live_xxxxxxxx")

# 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']}")

import { PromptGuard } from 'promptguard-sdk';

const pg = new PromptGuard({ apiKey: 'pg_live_xxxxxxxx' });

// Validate before executing a tool
const result = await pg.agent.validateTool(
  'my-agent',
  'execute_code',
  { code: "print('hello')" }
);

if (result.allowed) {
  // Safe to execute
  await executeTool(toolName, args);
} else {
  console.log(`Blocked: ${result.blocked_reasons.join(', ')}`);
}

Risk Levels

Level	Score Range	Action
`safe`	0.0 - 0.2	Allow
`low`	0.2 - 0.4	Allow with logging
`medium`	0.4 - 0.6	May require review
`high`	0.6 - 0.8	Block or require approval
`critical`	0.8 - 1.0	Always 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

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

Overview

Endpoints

API Reference

api-keys

usage

projects

agent

security

guard

enroll

shadow-exceptions

policies

overlays

tool-requests

GitHub Webhooks

Agent Security API

Agent Security API

Why Agent Security?

Endpoints

Validate Tool Call

Get Agent Stats

Register Agent

Rotate Agent Credential

End Agent Session

Agent Security Health

Get Managed Policy

SDK Usage

Risk Levels

Blocked Tools (Default)

Project Isolation

Best Practices

​Agent Security API

​Why Agent Security?

​Endpoints

​Validate Tool Call

​Get Agent Stats

​Register Agent

​Rotate Agent Credential

​End Agent Session

​Agent Security Health

​Get Managed Policy

​SDK Usage

​Risk Levels

​Blocked Tools (Default)

​Project Isolation

​Best Practices

Agent Security API

Why Agent Security?

Endpoints

Validate Tool Call

Get Agent Stats

Register Agent

Rotate Agent Credential

End Agent Session

Agent Security Health

Get Managed Policy

SDK Usage

Risk Levels

Blocked Tools (Default)

Project Isolation

Best Practices