← Blog

Agno Security: The AgentOS Controls That Need Explicit Configuration

Parminder Singh
Parminder Singh··6 min read
Summarize with AI

Agno AgentOS includes JWT verification, endpoint scopes, request copies, optional user isolation, and persistent approval records. Several protections depend on explicit settings or application-side authorization. This guide turns the current Agno documentation into a security acceptance review and keeps LLM request enforcement inside its real HTTP boundary.

Platform & Architectureai-securityagentic-aiidentity-and-authorizationpolicy-enforcementarchitecture
Agno Security: The AgentOS Controls That Need Explicit Configuration

Agno AgentOS can verify JWTs, check endpoint scopes, isolate user-owned records, copy components for each run, and pause protected tools for approval. Those controls sit at different boundaries. Several require explicit configuration. A deployment can turn on authorization while leaving JWT audience checks or per-user data isolation unset.

The useful security review is a set of failed requests, not a tour of the settings screen. I want to walk through the tests that prove caller identity and endpoint permission, data ownership, runtime isolation, and approval authority. Then I will mark the point where AgentOS security ends and outbound LLM request policy begins.

TL;DR

  • AgentOS can verify JWTs and enforce scopes on mapped endpoints, with audience checking configured separately.
  • User isolation for JWT callers is opt-in, while an admin scope receives an unscoped view.
  • Core run endpoints copy components, but models, databases, knowledge resources, MCP handles, and some tools remain shared by reference.
  • Approval records persist workflow state; the application still authorizes the resolver.

JWT verification needs an audience test

Agno's Security and Auth documentation says authorization=True activates authentication and endpoint authorization. JWT signatures are checked with configured public keys. Tokens can come from the AgentOS Control Plane or an application backend, as well as an external identity provider. AgentOS can accept multiple verification keys and use a local JWKS file for key selection.

Signature verification establishes who issued a valid token. Audience verification checks the token's intended recipient. Here, that recipient is this AgentOS. Agno exposes that second check through verify_audience=True, with the expected value defaulting to the AgentOS ID unless an audience is supplied. I would make this a release gate because a valid token intended for a neighboring service should fail here.

Start with an invalid signature. Then test a valid signature with the wrong audience and an expired token. Record the HTTP response and the configuration version used for the test. Rotate a key, refresh the validator according to the deployment procedure, and repeat the valid request.

Endpoint scopes are the API authorization boundary

AgentOS reads permission strings from a JWT claim and gates endpoints against those scopes, with documented examples that include agents:read and an ID-specific permission to run one agent. A wildcard permits any agent run. agent_os:admin grants full access. Service-account tokens use their stored scopes. Custom REST routes need explicit mappings because built-in scope behavior cannot infer the intended permission for application code.

This is where a broad agent_os:admin grant can erase the value of finer scopes. The admin scope includes access to session and memory records, plus trace queries. Those records can contain user prompts and model output alongside runtime state. Treat admin assignment as a production change with an owner and expiry review. A failed request is a poor reason to widen the grant.

The acceptance matrix should use one principal per role. Attempt agent discovery, one permitted run, one prohibited run, a trace query, and a session read. Capture denied responses as carefully as successful ones. A role description in the Control Plane is documentation. The negative requests are evidence that the mapping held.

For a wider view of where framework controls sit, see the agentic AI framework security comparison. Agno's endpoint scopes govern AgentOS APIs. They do not replace policy on the content and destination of a model request.

User isolation changes the meaning of stored ownership

For JWT callers, Agno documents user isolation as opt-in. Setting user_isolation=True threads the verified JWT subject into user-owned reads and writes. It also checks ownership for run continuation and verifies ownership on workflow WebSocket reconnection. Admin callers bypass that filtering. Service accounts execute under their own sa:<name> identity.

That setting deserves its own multi-tenant test. Create one session under user A and another under user B. A non-admin token for user A should fail to retrieve, cancel, resume, or continue user B's private run. Repeat the read with an authorized administrator and preserve the resulting access event in the identity or gateway logs.

Agno also notes that some domains can expose shared rows with no owner. The test data should include a shared record so the reviewer can distinguish intentional visibility from a cross-user leak. Run it with two browser windows and two JWT subjects, using one session identifier copied across them. The second window should show a denial instead of another user's conversation.

This is the storage side of the post-authentication gap. Verified identity has to survive each hop that reads or changes user state.

Fresh run copies still contain shared objects

Core run endpoints call deep_copy() on the registered agent, team, or workflow. Agno says mutable fields are copied when possible. It also says models, databases, knowledge resources, MCP tool handles, and some tools are shared by reference so their connection pools remain available. Fields that cannot be copied fall back to the original value.

The control reduces accidental state carryover in copied components. Shared custom objects still need a concurrency review because a mutable cache inside a custom tool can cross requests even when the agent object itself was copied. An MCP client that stores per-run data on a shared handle can create the same problem.

Test this with two concurrent users whose requests carry visibly different marker values. Inspect the tool, model wrapper, database adapter, and MCP client after both runs. Any state retained on a shared object needs an explicit reason and a synchronization strategy that preserves the tenant boundary. Runtime copying is one control. Safe shared objects remain an application responsibility.

Approval records preserve state, not resolver authority

Agno's approval documentation describes a persistent pause-and-resume flow. A protected tool creates a pending database record. An administrator resolves it, and a continuation by run ID checks the stored resolution. expected_status="pending" supports a compare-and-set style update that prevents two resolvers from silently overwriting the same pending state.

The same page states that the application must authorize who can resolve and continue runs. A trusted SDK caller can supply resolved requirements directly. Security review therefore needs two layers: the Agno approval transition and the application authorization around the resolver.

First, try to resolve the approval with an ordinary user. Repeat the attempt with an authorized reviewer and a service account lacking the review permission. Then attempt a second resolution after the state changed. Preserve the pending row, denial events, accepted resolver identity, resolution time, and continued run. I would block a production release if the team can demonstrate the approval screen but cannot show the authorization check behind its button.

Public and surface-specific routes belong in the inventory

Agno exempts discovery and documentation routes such as health, info, OpenAPI, and documentation pages from the central JWT requirement. Slack and Telegram use their own request verification, as does the WhatsApp interface. An enabled MCP Server Card is public, while MCP OAuth can delegate authentication to its configured provider.

A route inventory should label each surface with its verifier and expected unauthenticated behavior, then record its scope rule and data exposure. Put the inventory beside the reverse proxy policy because Agno assigns rate limiting, WAF rules, IP allowlists, and mTLS to that outer layer. The AI agent security guide covers the wider stack; this review stays with the AgentOS controls and their adjacent infrastructure owners.

DeepInspect

AgentOS secures its API surfaces and runtime state. DeepInspect covers authenticated HTTP traffic deliberately routed from the Agno application to an LLM endpoint. The application supplies identity and role context. DeepInspect evaluates prompt classification and destination under versioned policy before forwarding an allowed request.

The boundary excludes local tool execution, shared Python objects, approval resolution, MCP traffic that takes another route, and direct model calls that bypass the proxy. For routed calls, the independent decision record adds policy evidence beside Agno's trace and run records. That is the layer where prompt inspection in production can be bound to the caller instead of a shared model credential.

Book a technical deep dive at deepinspect.ai.

Frequently asked questions

Is Agno authorization enabled by default?

Agno documents authorization=False as the default for JWT scope enforcement. Configured security keys can still activate authentication behavior, and service-account credentials follow their own verification path. Production review should inspect the effective configuration. It should also run denied-request tests instead of inferring behavior from one environment variable.

Does AgentOS isolate each user's data automatically?

JWT authentication and user isolation are separate settings. For JWT callers, user isolation is off by default. Enabling it binds supported reads and writes, plus run-ownership checks, to the verified subject. Administrators with the configured admin scope receive an unscoped view, so their access needs separate monitoring.

Does component copying isolate every tool and connection?

Core run endpoints start with a fresh component copy, but Agno lists models, databases, knowledge resources, MCP handles, and some tools as shared by reference. Custom objects that retain mutable state need concurrency tests. They also need tenant-isolation tests.

Does an Agno approval prove the resolver was authorized?

The stored approval proves the transition that Agno recorded. The application is responsible for deciding who may resolve and continue the run. A complete evidence package joins the approval row to the resolver's authenticated identity and the application's authorization decision.