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": "read_file",
  "arguments": {
    "path": "/tmp/output.txt"
  },
  "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) (from staging, 2026-10-31)

{
  "allowed": true,
  "risk_score": 0.0,
  "risk_level": "safe",
  "reason": "Tool call approved",
  "warnings": [],
  "blocked_reasons": []
}

Response (Needs review): the same call with "tool_name": "write_file" and a content argument. write_file is on the default review list, so it is not allowed until a person approves it:

{
  "allowed": false,
  "risk_score": 0.0,
  "risk_level": "medium",
  "reason": "Tool call requires human review",
  "warnings": [],
  "blocked_reasons": ["Tool call requires human review"]
}

Response (Blocked): "tool_name": "run_command", which is on the default blocked list:

{
  "allowed": false,
  "risk_score": 1.0,
  "risk_level": "critical",
  "reason": "Tool 'run_command' is blocked for security reasons",
  "warnings": ["blocked_tool"],
  "blocked_reasons": ["Tool 'run_command' is blocked for security reasons"]
}

The agent’s behaviour profile can add to a verdict: an unusual pattern for this agent_id appears in warnings and as an Anomaly detected: ... entry in blocked_reasons.

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": 0,
  "anomalies_detected": 2
}

active_sessions is always 0 and is marked deprecated in the API schema. PromptGuard does not retain agent session state across requests, so there is nothing to count. The field is scheduled for removal in the next API version — do not build on it.

Enforcement is opt-in per project

An agent’s policy — allowed_tools, blocked_tools, require_approval — decides validate-tool verdicts only while the project’s agent_policy_enforced setting is on. It is off by default: policies you write are shown on the dashboard’s Agent Security page and enforce nothing until you turn enforcement on there, or via the dashboard API:

PATCH /dashboard/projects/{project_id}/settings
{ "agent_policy_enforced": true }

The project response carries the current value. While enforcement is off, every agent gets the platform-default tool lists. When it is on, an empty allowed_tools means no allowlist is configured (the defaults stand), a non-empty one replaces the default allowlist, and blocked_tools is added to the platform defaults — a policy can narrow what an agent may do, never re-enable a dangerous default.

End Agent Session (deprecated)

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

This endpoint is a no-op. Server-side agent session state is not retained across requests, so there is no session to end. The route still returns 200 with the same keys as before plus "deprecated": true, and sends Deprecation: true and Sunset: Wed, 09 Dec 2026 00:00:00 GMT. It will be removed on or after that sunset date — stop calling it.

{
  "status": "session_ended",
  "agent_id": "agent-123",
  "session_id": "sess-456",
  "deprecated": true
}

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

This poll doubles as the device’s heartbeat: each call updates the device’s Last seen in the fleet view. A device that shows never has enrolled but has not yet polled — check that the agent is installed and running on that machine. 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()  # Uses PROMPTGUARD_API_KEY env var

tool_name, arguments = "run_command", {"command": "ls /tmp"}

# Validate before executing a tool
result = pg.agent.validate_tool(
    agent_id="my-agent",
    tool_name=tool_name,
    arguments=arguments,
)

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

const { PromptGuard } = require('promptguard-sdk');

const pg = new PromptGuard();  // Uses PROMPTGUARD_API_KEY env var

async function guardedCall(toolName, args) {
  // Validate before executing a tool
  const result = await pg.agent.validateTool('my-agent', toolName, args);

  if (result.allowed) {
    // Safe to execute
    await executeTool(toolName, args);
  } else {
    // The Node SDK returns camelCase fields: blockedReasons, riskScore, riskLevel
    console.log(`Blocked: ${result.blockedReasons.join(', ')}`);
  }
}

guardedCall('run_command', { command: 'ls /tmp' });

Both print Blocked: Tool 'run_command' is blocked for security reasons. The Python SDK returns the response as a dict with the wire’s snake_case keys.

Risk Levels

The level follows from why the verdict was reached, not from risk_score ranges:

Level	When	`allowed`
`safe`	The tool passed every check	`true`
`low`	Allowed, with warnings about its arguments	`true`
`medium`	The tool needs human review (`write_file`, `create_file`, `modify_file`, `send_message`, `post`, `api_call`, or arguments risky enough to need it)	`false`
`high`	Dangerous or injection patterns in the arguments	`false`
`critical`	The tool is on the blocked list (`risk_score` 1.0)	`false`

Blocked Tools (Default)

These tools are blocked by default:

Shell and command execution: execute_shell, run_command, shell, bash, exec, system, subprocess, os.system
File deletion: delete_file, remove_file, rm, rmdir, unlink
Process control: kill_process, terminate
System changes: modify_system, change_permissions, chmod, chown
Network sends: send_email, http_post, upload_file

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 calls whose blocked_reasons include Anomaly detected
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

SDK Reference

API Reference

api-keys

usage

projects

SIEM export

guardrails

fleet-device

agent

security

mcp

security-testing

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

Enforcement is opt-in per project

End Agent Session (deprecated)

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

​Enforcement is opt-in per project

​End Agent Session (deprecated)

​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

Enforcement is opt-in per project

End Agent Session (deprecated)

Agent Security Health

Get Managed Policy

SDK Usage

Risk Levels

Blocked Tools (Default)

Project Isolation

Best Practices