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": 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.

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
}

An agent has exactly one active credential, enforced by a database constraint. If two rotations race, one wins and the other gets 409 with code CREDENTIAL_ROTATION_CONFLICT — retry it. A 409 never means the credential forked; it means yours did not land.

{
  "error": {
    "message": "Another rotation is in flight or this agent has no active credential; retry.",
    "type": "conflict_error",
    "code": "CREDENTIAL_ROTATION_CONFLICT"
  }
}

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(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

guardrails

fleet-device

agent

security

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

Register Agent

Rotate Agent Credential

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

​Register Agent

​Rotate Agent Credential

​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

Register Agent

Rotate Agent Credential

End Agent Session (deprecated)

Agent Security Health

Get Managed Policy

SDK Usage

Risk Levels

Blocked Tools (Default)

Project Isolation

Best Practices