AGNT Guardrails

Agents running unsupervised in production need boundaries. AGNT Guardrails are the safety controls built into every layer of the platform — rate limits, distributed locks, account isolation, certificate lifecycle, and supervision modes. They're not a separate product. They're cross-cutting constraints enforced automatically across every AGNT API.

Why AGNT Guardrails

Most agent platforms bolt on safety as an afterthought — a rate limiter here, an access check there. That works until an agent spins up 10,000 API calls in a loop, or two concurrent processes corrupt the same conversation, or a revoked credential keeps serving requests for another hour.

AGNT treats safety as infrastructure. Every request passes through rate limiting. Every chat processing operation acquires a distributed lock. Every database query is scoped to the caller's account. Revoked certificates stop working immediately, not eventually. These aren't features you enable — they're always on.

Quick Start

Guardrails are enforced automatically. There's nothing to configure for the defaults. But there are account-level settings you can tune.

Check your account settings

curl https://api.agnt.ai/account/settings \
  -H "Authorization: Bearer $TOKEN"

Update account settings

curl -X PUT https://api.agnt.ai/account/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "supervisionMode": "supervised",
    "autoProvisionUsers": true
  }'

Test a rate limit

Hit any endpoint more than 1000 times in a minute and you'll get a 429 Too Many Requests response. The response includes Retry-After headers so clients can back off gracefully.

See a distributed lock in action

Send two POST /chats/:chatId/process requests simultaneously for the same chat. The first acquires the lock. The second returns 409 Conflict. This is intentional — concurrent processing of the same conversation produces garbage output.

Core Concepts

Rate Limiting

Every API endpoint enforces a standard rate limit of 1000 requests per minute per account. This applies uniformly across all endpoints — management APIs, delegated APIs, and webhook callbacks.

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header indicating how long to wait. Well-behaved clients should respect this header. Agents should implement exponential backoff.

The limit is per-account, not per-user or per-key. All API keys and certificates belonging to an account share the same quota.

Distributed Locks

Chat processing uses Redis-based distributed locks with a 30-second TTL to prevent concurrent processing of the same conversation. When a chat is being processed:

1. The processing request acquires a lock keyed to the chat ID
2. Any other request to process the same chat receives 409 Conflict
3. The lock auto-releases after 30 seconds (safety net if the process crashes)
4. On successful completion, the lock releases immediately

This prevents a class of bugs where two concurrent LLM calls see the same message history and produce duplicate or contradictory responses. The 30-second TTL is a safety net — if a process hangs or crashes, the lock expires and the chat becomes processable again.

Why 409 and not a queue? Queuing concurrent requests silently would mask bugs. If your system is sending concurrent process requests for the same chat, that's a bug in your integration — you want to know about it, not have it silently papered over.

Auto-Provisioning Controls

When an API call is made with a delegated JWT (acting on behalf of an end user), AGNT will auto-create a user record from the JWT claims if one doesn't already exist. This is how end users get provisioned without a separate signup flow.

Key constraints:

• Delegated JWTs only. System-level JWTs (management API keys) never trigger auto-provisioning. This prevents accidental user creation from internal tooling.
• JWT claims become user data. The sub, email, and name claims from the JWT populate the user record.
• Account-scoped. The auto-provisioned user belongs to the account that owns the JWT signing certificate.

Account Isolation

Every database query in AGNT is scoped to the caller's account. There is no API endpoint, query parameter, or header that allows accessing another account's data. This is enforced at the data access layer, not the route layer — so even internal bugs can't leak data across accounts.

This means:

• GET /chats returns only your account's chats
• GET /users returns only your account's users
• GET /tasks returns only your account's tasks
• Search, analytics, and export endpoints all enforce the same scope

There is no admin override for cross-account data access.

Certificate Lifecycle

Certificates are the authentication mechanism for delegated API access (acting on behalf of end users). They have a strict lifecycle:

Revocation is immediate. The moment a certificate is revoked via DELETE /certificates/:id/revoke, all subsequent requests using that certificate are rejected. There is no propagation delay, no cache TTL to wait out. This is critical for incident response — if a certificate is compromised, one API call stops all access.

Endpoints:

Super Admin Boundaries

AGNT exposes administrative endpoints for platform-level operations (account management, system configuration, diagnostics). These endpoints are restricted to users with @agnt.ai email addresses.

This is a hard boundary, not a role. There is no "make me an admin" setting. If your email domain isn't @agnt.ai, admin endpoints return 403 Forbidden. This prevents privilege escalation from compromised customer accounts.

Supervision Modes

Tasks in AGNT support two execution modes:

Supervision mode is set per-account via account settings. It applies to all task execution within that account. This is the global safety switch — set it to supervised during initial rollout, switch to unsupervised once you trust the agent's behavior.

curl -X PUT https://api.agnt.ai/account/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"supervisionMode": "supervised"}'

Account Settings

Account-level settings control platform-wide behavior for your organization.

# Get current settings
curl https://api.agnt.ai/account/settings \
  -H "Authorization: Bearer $TOKEN"

# Update settings
curl -X PUT https://api.agnt.ai/account/settings \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "supervisionMode": "unsupervised",
    "autoProvisionUsers": true
  }'

API Reference

Guardrails are cross-cutting — they're enforced automatically rather than called directly. The endpoints below are the ones you interact with to configure guardrail behavior.

Account Settings

Certificates

Error Responses from Guardrails

For Coding Agents

Guardrails affect how you integrate with AGNT. Here's what matters:

• Implement retry with backoff. You will hit 429s during high-throughput operations. Respect the Retry-After header. Exponential backoff with jitter is the right pattern.
• Don't parallelize chat processing. One POST /chats/:chatId/process at a time per chat. If you get a 409, it means another process is already handling it — wait for it to finish, don't retry immediately.
• Use delegated JWTs for end-user actions. This triggers auto-provisioning and ensures correct account scoping. Use management API keys for admin operations only.
• Revoke certificates immediately on compromise. Don't delete and recreate — revoke first, then create a new one. Revocation is instant; deletion might leave a window.
• Start supervised, go unsupervised later. Set supervisionMode: "supervised" during development and initial production rollout. Switch to unsupervised once you've validated agent behavior through traces and analytics.
• Trust account isolation. You don't need to add account-scoping logic to your queries — AGNT enforces it at the data layer. Focus on your application logic, not access control.

For Product Teams

• Rate limits protect your budget. A misconfigured agent loop won't run up a $50,000 LLM bill — it'll hit the rate limit and stop. Monitor 429 responses in your analytics to catch runaway processes early.
• Supervision mode is your rollout dial. Start every new agent in supervised mode. Review its proposed actions for a week. When you're confident, flip to unsupervised. You can flip back at any time.
• Certificate management is incident response. If an API key is exposed in a log or a public repo, revoke the certificate immediately. Access stops within the same second. No waiting for cache expiration or key rotation.
• Account isolation means compliance by default. Customer data never crosses account boundaries. There's no configuration needed and no way to accidentally expose data to the wrong account. This simplifies SOC 2 and GDPR conversations significantly.
• Distributed locks prevent duplicate responses. If users are reporting duplicate or contradictory AI responses, check whether your integration is sending concurrent process requests. The lock system is designed to prevent this — if it's happening, you're bypassing the lock somehow.