Dynamic Agents

Build agents, teams, and workflows per request from JWT claims, user input, and other request-time context.

v2.6.0

Build a fresh Agent, Team, or Workflow for each incoming request. A factory is a callable that AgentOS invokes per request, so tools, instructions, model, and database scope can depend on who's calling.

Use a running PostgreSQL database with the ai user, password, and database on port 5532, or replace the example db_url. Install the server and driver dependencies and set the model key in its terminal:

uv pip install -U "agno[os]" openai "psycopg[binary]"
export OPENAI_API_KEY="your_openai_api_key"

Save the first example as tenant_factory.py and run python tenant_factory.py. Later fragments adapt the objects from that example. Application-specific helpers and tools must be supplied by your application.

tenant_factory.py
from agno.agent import Agent, AgentFactory
from agno.db.postgres import PostgresDb
from agno.factory import RequestContext
from agno.models.openai import OpenAIResponses
from agno.os import AgentOS

db = PostgresDb(
    id="factory-demo-db",
    db_url="postgresql+psycopg://ai:ai@localhost:5532/ai",
)


def build_tenant_agent(ctx: RequestContext) -> Agent:
    user_id = ctx.user_id or "anonymous"
    return Agent(
        model=OpenAIResponses(id="gpt-5.4"),
        db=db,
        instructions=f"You are a helpful assistant for tenant {user_id}. Be concise.",
        markdown=True,
    )


tenant_factory = AgentFactory(
    id="tenant-agent",
    db=db,
    factory=build_tenant_agent,
    name="Per-tenant assistant",
    description="Builds a personalized agent per tenant on each request.",
)

agent_os = AgentOS(agents=[tenant_factory])
app = agent_os.get_app()

if __name__ == "__main__":
    agent_os.serve(app="tenant_factory:app", port=7777)

Hit POST /agents/tenant-agent/runs and the factory is invoked with a RequestContext for that request.

id and db are required on AgentFactory. The factory's id overrides any id set on the Agent returned by the callable.

When to Use a Factory

Use a plain Agent / Team / Workflow when the component is shared across all callers. Reach for a factory when construction depends on the request.

Use CasePattern
Tools or model vary per caller roleAgentFactory reading ctx.trusted.claims
Members vary per tenantTeamFactory returning a Team with tenant-specific agents
Pipeline shape varies per requestWorkflowFactory returning a different step graph
Client picks persona, depth, or styleFactory with input_schema reading ctx.input

GET /agents/{id}, GET /teams/{id}, and GET /workflows/{id} (the component-detail endpoints) return the factory's metadata without invoking it. See the Factories reference for per-endpoint behavior and discovery payload shape.

Learn How To

AgentFactory

Produce a fresh Agent per request from verified claims or client input.

TeamFactory

Compose a fresh Team and its members for each request.

WorkflowFactory

Compose pipelines whose step graph depends on the request.

RequestContext

Fields, sources, and identity precedence.

JWT Middleware

Populate ctx.trusted.claims from verified JWTs.

Factories Reference

Class signatures, parameters, and exceptions.

Developer Resources