lauren-ai

Adds content safety filters to lauren-ai agents using @use_guardrails for input and output checks. Use when an agent needs prompt injection protection, PII redaction, topic filtering, length limiting, or LLM-powered content evaluation. Also covers creating custom guardrail classes injectable via @guardrail.

Aggregates per-model telemetry from SignalBus events using CostTracker and a custom PerformanceMetrics collector. Use when tracking total LLM calls, token consumption, average latency, error rate, and cost per model across agent runs.

Submit agent tasks to an asyncio queue and process them with a background worker, returning results by task ID. Use when you need non-blocking agent execution in web handlers, batch processing pipelines, or any situation where callers should not wait for agent completion.

Builds AI agents with the lauren-ai framework using @agent, @use_tools, and AgentRunner. Use when defining an agent class, setting up lifecycle hooks, streaming responses, implementing agent delegation, or configuring the agentic loop with tools, guardrails, and memory.

Creates tools for lauren-ai agents using @tool() on async functions or classes. Use when implementing a @tool() function or class, working with ToolContext for DI injection, adding caching, HITL approval, or using built-in skills like WebSearchTool, HttpFetchTool, or CodeExecutionTool.

Implements an in-memory calendar management tool for agents using @tool() class-form. Use when building agents that create, query, or cancel calendar events, with ISO 8601 time handling and date-based filtering. Supports @set_metadata for tool-type annotation.

Subscribe to SignalBus lifecycle events to build lightweight tracers that record LLM call spans, tool call spans, and run summaries. Use when you need observability into agent execution without adding a full tracing backend, or when building cost/latency dashboards.

Elicits step-by-step reasoning from models to improve accuracy on complex tasks. Use when the task involves multi-step logic, math, code analysis, or planning; when zero-shot answers are unreliable; or when you need to extract and inspect the model's reasoning separately from its final answer.

Configures agent behaviour via @agent() parameters and AgentConfig. Use when adjusting max_turns, temperature, max_tokens_per_turn, max_cost_usd, tool_error_policy, memory window, or when the agent must stop after a fixed number of turns.

Provides copy-paste complete Lauren AI agent implementations for the most common production scenarios. Covers a research agent with web search and knowledge base, a customer service bot with memory and guardrails, a data-analysis agent with database tools, and a sequential pipeline agent. Use when scaffolding a new agent or when a complete working example is needed rather than API reference.

Implements an agent tool for dispatching email notifications with a swappable backend. Use when building agents that send emails or notifications, with an in-memory backend for testing and a pluggable abstract backend for production SMTP or API-based senders.

Implements a provider fallback chain that tries multiple LLM providers in order, returning the first success. Use when you need resilience against provider outages, want cost-based fallback (expensive to cheap), or need graceful degradation to a rule-based response.

Injects labeled input/output examples into system prompts or message history to steer model behavior with in-context learning. Use when the task has a consistent input/output format, when zero-shot instructions are insufficient, or when you need dynamic example selection per request.

Implements a sandboxed file system tool for agents using @tool() class-form. Use when building tools that read, write, or list files within a restricted base directory, with path traversal protection to prevent access outside the allowed workspace.

Enforces per-minute request and token-per-minute limits on LLM API calls with automatic retry and exponential backoff. Use when deploying multi-user applications that share an API key, when provider rate limits must not be exceeded, or when per-user quotas are needed.

Manages memory tiers in lauren-ai agents — short-term rolling window, conversation history, user memory facts with @remember, and vector store for RAG. Use when adding persistent memory to an agent, implementing @remember() for long-term facts, using ConversationStore across sessions, or building RAG with InMemoryVectorStore.

Ports AI agent code from LangChain or the raw OpenAI SDK to the lauren-ai framework. Provides side-by-side equivalents for chains, agents, tools, memory, and prompts. Use when converting LangChain or OpenAI-SDK-based agent code to lauren-ai, or when a user is familiar with those frameworks and needs the lauren-ai equivalents.

Implements multi-agent delegation where an orchestrator agent hands off tasks to specialist agents via a tool call. Use when building a system where a triage or coordinator agent routes requests to domain-specific agents (e.g. billing, support, technical).

Shows how to accumulate state across multiple tool calls within a single agent run using AgentContext.metadata. Use when building stateful tools like shopping carts, accumulators, or multi-step workflows where intermediate state must persist between tool invocations within a run.

Attaches post-generation content filters to agents to redact PII, enforce topic scope, cap response length, or block harmful content before it reaches users. Use when agents generate sensitive content, when compliance requires PII removal, or when responses must stay within a defined topic area.

Detects and blocks prompt injection attempts in user input before they reach the LLM. Use when agents accept free-text user input, when handling untrusted data in RAG pipelines, or when compliance requires logging and blocking jailbreak attempts.

Manages multiple named prompt versions with A/B routing by user-id hash. Use when running controlled prompt experiments, when rolling out a revised system prompt to a percentage of users, or when you need reproducible rollback to a prior prompt version.

Validates agent responses against rules or schemas and retries with a corrective prompt when validation fails. Use when the agent must return JSON, structured data, or text meeting specific criteria; when using a weaker model that occasionally produces malformed output; or when reliability is more important than latency.

Secures lauren-ai agents against prompt injection and identity spoofing using the ToolContext trust chain. Use when tools must verify the acting user's identity, when building financial or administrative operations, or when tools should never trust LLM-supplied user_id parameters.

Streams LLM responses chunk-by-chunk from an agent via runner.run_stream(). Use when building real-time UIs, SSE endpoints, WebSocket streaming, or any feature that needs to display tokens as they arrive rather than waiting for the full response.

Shows how an orchestrator agent spawns multiple sub-agents and aggregates their results. Use when building hierarchical multi-agent systems where a coordinator delegates specialised tasks to sub-agents, either sequentially or in parallel via asyncio.gather.

Builds system prompts dynamically with composable sections, template variable substitution, and fluent builder API. Use when agent system prompts need to vary by user, context, or feature flag; when assembling role + context + constraints programmatically; or when sharing prompt fragments across multiple agents.

Tests lauren-ai agents with zero real network calls using MockTransport and AgentTestClient. Use when writing unit tests for agents, tools, or guardrails, simulating multi-turn tool-use flows, testing conversation memory, or verifying secure tool behaviour with mocked execution context.

Splits long documents into overlapping chunks for RAG pipelines and context window management. Use when a document exceeds model context limits, when building vector store indexes, or when chunking text for batch embedding. Provides RecursiveCharacterSplitter that tries paragraph, line, sentence, word, and character separators in priority order.

Tracks token consumption and USD cost per conversation or user, enforces spending budgets, and surfaces usage reports. Use when billing users per-conversation, when capping agent costs in production, or when you need to monitor and alert on LLM spend.

Defines and registers tools for lauren-ai agents using @tool() on async functions or classes. Use when adding LLM-callable tools, injecting DI services into tools via ToolContext, attaching tools to agents with @use_tools(), or testing tool dispatch with MockTransport.

Inspects the raw token stream a real LLM emits for a given system + user prompt, with chunk boundaries preserved. Use when debugging dense / unformatted model output (run-on text, missing newlines, glued-on emoji), validating that a system-prompt change produces the markdown structure you expected, or comparing two prompts / models side-by-side without spinning up the agentic loop or any tools.

Scope tool execution behind permission levels (read_only, mutate, admin). Use when different users or agent roles should have different tool access rights, injecting the permission level via ToolContext metadata and declaring requirements via @set_metadata.

SQL query tool with read/write guard using SQLite in-memory (or any sqlite3-compatible connection). Use when an agent needs to query or mutate a relational database, with configurable read-only mode to prevent accidental writes. Supports @set_metadata for mode annotation.

Invoke external REST APIs from inside an agent using httpx.AsyncClient. Supports GET/POST/PUT/DELETE with optional auth header propagation from the execution context. Use when an agent needs to call external services, microservices, or webhooks.

Implements timeout wrappers and a circuit breaker pattern for agent runs. Use when protecting services from slow or failing agent calls, adding deadline enforcement via asyncio.wait_for, or implementing automatic circuit breaking to stop calling a degraded agent.

Implements per-tenant and per-user session isolation for agent conversations using namespaced conversation IDs. Use when building multi-tenant applications where different users or tenants must have fully isolated conversation histories that cannot bleed into each other.

Log each agentic loop step using lifecycle hooks on the @agent class. Use when you need structured per-step logs for debugging, auditing, or monitoring without modifying the runner or adding external infrastructure.

Implements a supervisor/router pattern where a central agent classifies user intent and dispatches to specialist agents. Use when building multi-agent systems that route requests based on domain (billing, technical support, general), implementing intent classification before delegation, or orchestrating specialist agents from a coordinator.

Execute Python code in a restricted sandbox using exec() with limited builtins, stdout capture, and asyncio timeout. Use when an agent needs to run user-supplied or LLM-generated Python code safely without access to the filesystem or dangerous builtins.