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 a tool call before allowing execution.
POST /api/v1/agent/validate-tool
{
"agent_id": "agent-123",
"tool_name": "write_file",
"arguments": {
"path": "/tmp/output.txt",
"content": "Hello world"
},
"session_id": "session-456"
}
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": []
}
{
"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
{
"agent_id": "agent-123",
"total_tool_calls": 1523,
"blocked_calls": 12,
"avg_risk_score": 0.15,
"active_sessions": 3,
"anomalies_detected": 2
}
Register Agent
Register a new agent identity and receive a one-time-visible credential.
POST /api/v1/agent/register
{
"agent_name": "billing-assistant",
"allowed_tools": ["read_invoice", "send_summary"]
}
{
"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
{
"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 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
{
"fleet": true,
"force_update_mode": "auto",
"pinned_channel": "stable",
"min_version_override": null
}
SDK Usage
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 |
execute_shell, run_command, bash, systemdelete_file, rm, rmdirkill_process, terminatesend_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
