# Waxell > Waxell is a platform for building governed AI agents with built-in observability, policy enforcement, and production-grade infrastructure. This file provides an index of all documentation for LLM consumption. > Last generated: 2026-10-21 ## Links - [Website](https://waxell.ai) - [Documentation](https://waxell.ai/docs/) - [Dashboard](https://waxell.dev) - [Status](https://status.waxell.dev) - [Community Forum](https://community.waxell.dev) - [Security](https://waxell.ai/docs/security) - [Full Documentation for LLMs](https://waxell.ai/docs/llms-full.txt) ## Waxell Observe > LLM observability, cost tracking, and governance for AI applications ### Get Started - [Waxell Observe](https://waxell.ai/docs/observe/overview): Lightweight observability and governance for any Python AI agent framework. Track LLM calls, manage costs, and enforce policies without rewriting your agents. - [Quickstart: Observe Your Agents](https://waxell.ai/docs/observe/quickstart): Add full observability to your AI agents -- auto-instrumentation in 2 lines, decorators for structure, WaxellContext for full control. - [Installation & Configuration](https://waxell.ai/docs/observe/installation): Install waxell-observe and configure API credentials via environment variables, CLI config file, or programmatic setup. ### Instrumentation - [Auto-Instrumentation](https://waxell.ai/docs/observe/integrations/auto-instrumentation): Zero-code observability for 200+ AI/ML libraries including LLM providers, vector databases, agent frameworks, and more - [Decorator Pattern](https://waxell.ai/docs/observe/integrations/decorator): Add observability and governance to any Python function with the @observe decorator. - [Behavior Tracking](https://waxell.ai/docs/observe/features/behavior-tracking): Track tool calls, retrievals, decisions, reasoning, retries, and steps with decorators, convenience functions, or manual context methods. - [Advanced: Context Manager](https://waxell.ai/docs/observe/integrations/context-manager): Use WaxellContext for fine-grained control over observability and governance in complex agent workflows. - [Streaming](https://waxell.ai/docs/observe/integrations/streaming): Capture streaming LLM responses with proper token counting - [Multi-Agent](https://waxell.ai/docs/observe/integrations/multi-agent): Trace correlated multi-agent systems with shared sessions ### Tutorials - [Tell the Story of a Run](https://waxell.ai/docs/observe/tutorials/story-of-a-run): Turn a trace from a list of spans into a narrative anyone can read — task, steps, decisions, result, and what degraded — across all three integration modes. - [Auto-Instrumentation: Activity, Not Story](https://waxell.ai/docs/observe/tutorials/narrate-auto-instrumentation): What the two-line init() gives you, exactly where it stops, and the one-line change that turns activity into a narrated run. - [Decorator: Narrate With Three Lines](https://waxell.ai/docs/observe/tutorials/narrate-decorator): Start from @observe, add steps, a decision, and an explicit result, and open a fully narrated run in the UI. - [Context Manager: Full Control, Including Degrades](https://waxell.ai/docs/observe/tutorials/narrate-context-manager): Use `with waxell.context()` to narrate a multi-phase agent explicitly — steps, reasoning, decisions, result — and make every failed read and unavailable model visible as a span. - [How the AI Narrator Reads a Run](https://waxell.ai/docs/observe/tutorials/how-the-narrator-reads-a-run): What the run narrator consumes, how to enable it, what content capture controls, and why a narrated agent gets a better summary. - [Config Health: Presence Isn't Validity](https://waxell.ai/docs/observe/tutorials/config-health-doctor): Why a key that is set can still be dead, and how the controlplane doctor proves every configured integration works with a real call — including whether each agent's model id still exists. - [Reading the run page](https://waxell.ai/docs/observe/tutorials/reading-the-run-page): How to read a single agent run top to bottom — the outcome header, the three run statuses, the governance verdict, and what it means when a call has no prompt or response. - [Is my fleet alive?](https://waxell.ai/docs/observe/tutorials/is-my-fleet-alive): Last run, last status, next due and OVERDUE — how to see at a glance which scheduled agents are running, which are late, and which have never run. - [Managing errors](https://waxell.ai/docs/observe/tutorials/managing-errors): Every error your agents hit — failed runs, policy violations, failed tool and model calls, degraded steps — in one managed feed: acknowledge, resolve, mute, assign, file a ticket, and get a signed webhook any tracker can consume. ### Provider Integrations - [OpenAI](https://waxell.ai/docs/observe/integrations/openai): Instrument OpenAI API calls with automatic or manual tracing - [Anthropic](https://waxell.ai/docs/observe/integrations/anthropic): Instrument Anthropic Claude API calls with Waxell Observe - [LiteLLM](https://waxell.ai/docs/observe/integrations/litellm): Multi-provider observability with LiteLLM's unified API - [Claude Code & Cowork](https://waxell.ai/docs/observe/integrations/claude-code): Add observability, governance, and security guardrails to Claude Code and Claude Cowork sessions ### Features - [LLM Call Tracking](https://waxell.ai/docs/observe/features/llm-tracking): Track every LLM API call with model, token counts, cost, and prompt/response previews. - [Provider Routing — Use Waxell Routing Without the Runtime](https://waxell.ai/docs/observe/features/provider-routing): Dispatch LLM calls through Waxell with cross-provider fallback, capability filtering, and per-instance secret resolution — without adopting the Waxell runtime. - [Sessions](https://waxell.ai/docs/observe/features/sessions): Group related agent runs into sessions for multi-turn conversation tracking and aggregate analysis. - [User Tracking](https://waxell.ai/docs/observe/features/user-tracking): Track per-user costs, usage patterns, and agent interactions with opaque user identifiers. - [Cost Management](https://waxell.ai/docs/observe/features/cost-management): Track, estimate, and control LLM costs with client-side estimation, server-side calculation, and tenant-level overrides. - [Scoring](https://waxell.ai/docs/observe/features/scoring): Attach quality scores to agent runs using numeric, categorical, or boolean values from SDK or UI. - [Prompt Management](https://waxell.ai/docs/observe/features/prompt-management): Version, label, and retrieve prompts with content hashing for production traceability and a playground for testing. - [Conversation Tracking](https://waxell.ai/docs/observe/features/conversation-tracking) - [Evaluators (LLM-as-Judge)](https://waxell.ai/docs/observe/features/evaluators): Automate quality assessment of agent runs using configurable LLM-based evaluators and human annotation queues. - [Datasets & Experiments](https://waxell.ai/docs/observe/features/datasets-experiments): Build test datasets from production data, run systematic experiments across configurations, and compare results side by side. ### Governance - [Policy & Governance](https://waxell.ai/docs/observe/features/governance): Enforce execution policies with pre-run checks, budget controls, and mid-execution validation. - [Eval-Driven Governance](https://waxell.ai/docs/observe/features/eval-driven-governance): Turn evaluation scores into production guardrails. One evaluator measures quality offline AND enforces policy live — block hallucinations, catch PII leaks, gate prompt regressions, and produce continuous compliance evidence. - [Approval Workflows](https://waxell.ai/docs/observe/features/approval-workflows): Handle policy blocks with human-in-the-loop approval — terminal prompts, Slack, webhooks, or custom UI. - [Human-in-the-Loop](https://waxell.ai/docs/observe/features/human-in-the-loop): Capture interactive human input — terminal prompts, Slack messages, UI dialogs — as observable spans in your agent traces. - [Policy Categories & Templates](https://waxell.ai/docs/observe/features/policy-categories): All 49 policy categories and pre-built templates for governing AI agents -- operational guardrails, data and security boundaries, cognitive controls, OWASP LLM Top 10, regulatory compliance, end-user identity, and more. ### Governance / Operational Guardrails - [Rate Limit Policy](https://waxell.ai/docs/observe/governance/rate-limit): Enforce execution frequency limits on agent workflows -- per-minute, per-hour, per-day, concurrent, and burst rate limiting with distributed Redis counters. - [Budget Policy](https://waxell.ai/docs/observe/governance/budget): Token and cost budgets for workflows -- daily and per-workflow limits, warning thresholds, per-model caps, and block/warn/throttle actions when exceeded. - [Chargeback Attribution Policy](https://waxell.ai/docs/observe/governance/chargeback-attribution): Require cost-center / business-unit tags on every agent run so finance can attribute LLM spend by department. Optional auto-tagging with a fallback bucket. - [Scheduling Policy](https://waxell.ai/docs/observe/governance/scheduling): Control when workflows can run -- allowed hours, allowed days, blackout dates, and recurring maintenance windows, all timezone-aware. - [Time-of-Day Gating Policy](https://waxell.ai/docs/observe/governance/time-of-day-gating): Window-of-allowed-use enforcement with multiple per-day windows, overnight windows, IANA timezones, and workflow-type exemptions. Maps to SOX 404, ISO 27001, HIPAA access controls. - [Safety Policy](https://waxell.ai/docs/observe/governance/safety): Content and behavior safety controls for workflow execution -- PII detection, credential scanning, profanity filtering, step/tool limits, blocked tools, and human approval requirements. - [Kill Switch (Circuit Breaker) Policy](https://waxell.ai/docs/observe/governance/kill-switch): Emergency stop controls with automatic circuit breaker functionality -- track error rates, auto-disable failing agents, and recover automatically with Redis-backed state. - [Audit Policy](https://waxell.ai/docs/observe/governance/audit): Configurable audit logging for workflow execution -- input/output/step/tool-call logging with field redaction and retention controls. - [Operations Policy](https://waxell.ai/docs/observe/governance/operations): Enforce operational controls on workflow execution -- timeout monitoring with post-hoc warnings for SLA compliance and performance tracking. - [LLM Policy](https://waxell.ai/docs/observe/governance/llm): Govern which LLM models agents can use, enforce token budgets, and validate model compliance with allowlists and blocklists -- including versioned model name matching. - [Quality Policy](https://waxell.ai/docs/observe/governance/quality): Validate agent output quality with template-based checks (contains, regex, length), LLM judge scoring, JSON schema validation, and retry feedback -- post-execution quality gates. - [Content Policy](https://waxell.ai/docs/observe/governance/content): Input/output content scanning for PII, credentials, prompt injection, custom patterns, and blocked phrases -- with configurable warn, redact, and block actions. - [Spawn Limit Policy](https://waxell.ai/docs/observe/governance/spawn-limit): Tenant-wide concurrent ctx.spawn ceiling enforced at the dispatcher -- gates new child spawns before any dispatch happens. Runtime-plane only. ### Governance / Data & Security Boundaries - [Data Access Policy](https://waxell.ai/docs/observe/governance/data-access): Control which data sources agents can read from or write to — allowlists, blocklists, read-only enforcement, and per-query record volume limits. - [Network Policy](https://waxell.ai/docs/observe/governance/network): Control outbound HTTP requests from agents — domain allowlists and blocklists, wildcard patterns, protocol restrictions, and internal-only mode. - [Scope Policy](https://waxell.ai/docs/observe/governance/scope): Blast-radius governance — limits the maximum impact of a single agent execution by capping records modified/deleted, files changed, transaction amounts, and API write counts. - [Code Execution Policy](https://waxell.ai/docs/observe/governance/code-execution): Govern what code your AI agents can execute -- languages, commands, paths, packages, sandboxing, and human review. - [Input Validation Policy](https://waxell.ai/docs/observe/governance/input-validation): Pre-flight data validation that checks inputs for emptiness, size, type, HTML injection, and schema compliance before agent execution begins. - [Output Egress Format Policy](https://waxell.ai/docs/observe/governance/output-egress-format): OWASP LLM05 exfiltration prevention — scans agent outputs for base64 blobs, external URLs, data URIs, and Unicode obfuscation that signal data smuggling. ### Governance / Cognitive Governance - [Grounding Policy](https://waxell.ai/docs/observe/governance/grounding): Hallucination and factual accuracy governance — enforces minimum grounding scores, citation requirements, unsupported claim limits, and output confidence thresholds for RAG and research agents. - [Provenance Required Policy](https://waxell.ai/docs/observe/governance/provenance-required): OWASP LLM09b — strict per-claim citation enforcement. Every factual claim in agent output must carry a citation to a source on the tenant's approved list. - [Retrieval Policy](https://waxell.ai/docs/observe/governance/retrieval): RAG pipeline quality governance — relevance scoring, source freshness, collection allowlists, and source diversity enforcement for vector search and retrieval-augmented generation. - [Reasoning Policy](https://waxell.ai/docs/observe/governance/reasoning): Decision explainability and bias detection governance — enforce explanation requirements, alternative consideration, confidence thresholds, and bias detection for agent decision-making. - [Recursion Bound Policy](https://waxell.ai/docs/observe/governance/recursion-bound): OWASP LLM10c — cap reasoning depth, tool-call count, delegation depth, and user-turn count to prevent runaway agent loops. - [Prompt Injection Guard Policy](https://waxell.ai/docs/observe/governance/prompt-injection-guard): OWASP LLM01 — scan agent inputs and indirect retrieval/tool outputs for prompt-injection signals using heuristic patterns and an optional ML classifier. ### Governance / Agent Action Control - [Approval Policy](https://waxell.ai/docs/observe/governance/approval): Human-in-the-loop gates -- require human approval before workflow execution, before specific tools or actions run, or when cost exceeds a threshold. Includes session-start pre-approval and auto-approve by risk level. - [Delegation Policy](https://waxell.ai/docs/observe/governance/delegation): Multi-agent trust governance -- controls delegation depth, authorized delegates, concurrent sub-agent limits, and policy inheritance across agent hierarchies. - [Cross-Agent Isolation Policy](https://waxell.ai/docs/observe/governance/cross-agent-isolation): Prevent one agent from reading another agent's memory, scratchpad, tool state, or context. Agent-level analogue of multi-tenancy. - [Communication Policy](https://waxell.ai/docs/observe/governance/communication): Govern agent output channels -- allowed/blocked channels, message limits, disclaimer requirements, and channel-level access control. - [Domain Governance Policy](https://waxell.ai/docs/observe/governance/domain-governance): Per-call guards for Connect domain endpoints -- allowed/blocked domains and actions, payload-size limits, per-run call caps, approval gates, and audit logging. (E5 shadow-mode.) - [Signal Governance Policy](https://waxell.ai/docs/observe/governance/signal-governance): Control which signals can be dispatched, from what sources, with rate-limits and payload validation. Evaluates at signal ingestion -- BEFORE any agent execution begins. ### Governance / Allowlists - [Tool Allowlist Policy](https://waxell.ai/docs/observe/governance/tool-allowlist): Positive-list governance for tools -- only listed tools may be invoked. Differs from safety.blocked_tools (deny-only) by adding a hard allowlist. - [MCP Server Allowlist Policy](https://waxell.ai/docs/observe/governance/mcp-server-allowlist): Constrain which MCP servers an agent may register / connect to. Positive allowlist + always-deny list for the MCP ecosystem. - [Prompt Allowlist Policy](https://waxell.ai/docs/observe/governance/prompt-allowlist): Constrain named system-prompt templates. Cross-references the prompt-management system; enterprise compliance lever for vetted prompts. - [Tool Argument Schema Policy](https://waxell.ai/docs/observe/governance/tool-argument-schema): OWASP LLM06a — validate tool-call arguments against JSON schemas before invocation. Companion to tool-allowlist (which gates tool names). - [Agent Service Account Scope Policy](https://waxell.ai/docs/observe/governance/agent-service-account-scope): OWASP LLM06b enforcement — agents acting on SaaS surfaces (Confluence, Jira, Salesforce) must use a least-privilege service account instead of the raw user session. ### Governance / Trust, Privacy & Compliance - [Privacy Policy](https://waxell.ai/docs/observe/governance/privacy): Data privacy governance -- consent requirements, data residency enforcement, purpose limitations, and data minimization for GDPR, HIPAA, and custom privacy frameworks. - [Identity Policy](https://waxell.ai/docs/observe/governance/identity): Agent identity governance -- enforce AI disclosure requirements and prevent impersonation of humans or professional roles in agent outputs. - [Memory Policy](https://waxell.ai/docs/observe/governance/memory): Session memory governance -- enforce session isolation, cap memory item counts, restrict forbidden memory types, and signal purge-on-completion for agent context stores. - [Compliance Policy](https://waxell.ai/docs/observe/governance/compliance): Meta-validator that checks required sibling policies are active and properly configured -- regulatory profile validation for HIPAA, SOC 2, PCI-DSS, GDPR, and custom compliance frameworks. - [Context Management Policy](https://waxell.ai/docs/observe/governance/context-management) - [Data Residency Policy](https://waxell.ai/docs/observe/governance/data-residency): Pin agent execution to approved regions for data-sovereignty compliance. Aligned to ISO 42001 A.8.4, GDPR, and EU AI Act. - [Data Erasure Policy](https://waxell.ai/docs/observe/governance/data-erasure): Enforce GDPR Art-17 "Right to Erasure" and CCPA right-to-delete SLAs. Block processing and writes for subjects with pending erasure requests. - [Breach Notification Policy](https://waxell.ai/docs/observe/governance/breach-notification): Enforce regulatory breach-notification SLAs -- 72h GDPR Art-33, 60d HIPAA §164.404. Blocks agent activity until notifications are dispatched. - [Bias Trend Policy](https://waxell.ai/docs/observe/governance/bias-trend): Continuous fairness monitoring -- track the rate of bias flags over a rolling window and fire when it exceeds threshold. Aligned to NIST AI RMF MS-3.1 and EU AI Act Art-10. - [Model Card Required Policy](https://waxell.ai/docs/observe/governance/model-card-required): OWASP LLM03 / NIST AI RMF GV-1.1 — every model used by an agent must have a declared model card with a risk classification. Models without a card or above the policy ceiling are blocked. ### Governance / End-User Identity - [End-User Budget Policy](https://waxell.ai/docs/observe/governance/end-user-budget): Per-WaxellUser monthly spend caps -- enforce $/month limits on individual end-users behind a tenant. - [End-User Rate Limit Policy](https://waxell.ai/docs/observe/governance/end-user-rate-limit): Per-end-user and per-group request-rate caps -- protect against runaway sub-users and noisy customers. - [End-User Suspension Policy](https://waxell.ai/docs/observe/governance/end-user-suspension): Block runs for suspended end-users -- per-seat kill switch that takes effect at the next turn boundary. ### Governance - [Policy Recommendations](https://waxell.ai/docs/observe/features/recommendations): Automated policy suggestions based on your agent's actual runtime behavior -- token budgets, cost limits, timeouts, and safety bounds. - [Platform Assistant](https://waxell.ai/docs/observe/features/platform-assistant): The AI operations advisor built into Waxell — query your data, create policies, get proactive insights, and learn the platform through natural language. ### Troubleshooting - [FAQ](https://waxell.ai/docs/observe/troubleshooting/faq): Frequently asked questions about the Waxell Observe SDK -- setup, instrumentation, governance, and more. - [Common Errors](https://waxell.ai/docs/observe/troubleshooting/common-errors): Error reference for the Waxell Observe SDK -- what each error means and how to fix it. - [Common Mistakes](https://waxell.ai/docs/observe/troubleshooting/common-mistakes): Anti-patterns and gotchas when using the Waxell Observe SDK -- and how to fix them. ### API Reference - [REST API Reference](https://waxell.ai/docs/observe/api/endpoints): Complete REST API reference for the Waxell Observe endpoints, including runs, policy checks, events, model costs, LLM calls, sessions, users, scoring, and prompts. - [Python SDK Reference](https://waxell.ai/docs/observe/api/python-sdk): Complete API reference for all public classes, functions, and types in the waxell-observe Python package. ## MCP Governance > Govern Model Context Protocol servers — policy enforcement, PII scanning, and rug-pull detection ### Auto-Instrumentor - [MCP Governance: Secure and Monitor AI Agent Tool Calls](https://waxell.ai/docs/observe/mcp-governance/overview): What is MCP governance, why SDK-level beats gateway approaches, and how Waxell's three products work together. - [MCP Governance Quickstart](https://waxell.ai/docs/observe/mcp-governance/quickstart): Add MCP governance to your agent in one line -- see tool calls, policy checks, and PII scans in traces within 5 minutes. - [MCP Policy Configuration](https://waxell.ai/docs/observe/mcp-governance/policy-configuration): Configure allowlist and blocklist rules for MCP tool calls using the mcp:{server}:{tool} naming convention. - [MCP Approval Workflows](https://waxell.ai/docs/observe/mcp-governance/approval-workflows): Set up human-in-the-loop approval for blocked MCP tool calls -- prompt_approval, auto_approve, custom handlers. - [PII and Secret Scanning for MCP Tools](https://waxell.ai/docs/observe/mcp-governance/pii-scanning): Configure automatic PII and secret detection for MCP tool inputs and outputs -- block, warn, or redact sensitive data before it leaves your agent. - [Rug Pull Detection for MCP Tools](https://waxell.ai/docs/observe/mcp-governance/rug-pull-detection): Detect when MCP servers change tool descriptions -- SHA256 fingerprinting, change alerts, and blocking suspicious tool modifications. - [MCP Span Attributes Reference](https://waxell.ai/docs/observe/mcp-governance/reference): Complete reference for all waxell.mcp.* span attributes and OTel semantic conventions used by the MCP auto-instrumentor. ### Server Middleware - [Add Governance to Your FastMCP Server](https://waxell.ai/docs/observe/mcp-governance/middleware-quickstart): Add policy checks, PII scanning, rate limiting, and observability to your FastMCP server with GovernanceMiddleware -- zero to governed server in 10 minutes. - [Configure Governance Per Tool](https://waxell.ai/docs/observe/mcp-governance/middleware-per-tool): Configure governance differently for each tool in your FastMCP server using @governance decorators, constructor tool_configs, or server defaults. - [Connect Your Middleware to the Waxell Controlplane](https://waxell.ai/docs/observe/mcp-governance/middleware-controlplane): Connect GovernanceMiddleware to the Waxell controlplane for centralized policy management, remote policy checks, and fail-open resilience. - [Middleware API Reference](https://waxell.ai/docs/observe/mcp-governance/middleware-reference): Complete reference for GovernanceMiddleware, ToolGovernanceConfig, MiddlewareConfig, the @governance decorator, and server-side span attributes. ### Governance Proxy - [Governance Proxy Quickstart](https://waxell.ai/docs/observe/mcp-governance/proxy-quickstart): Wrap any third-party MCP server with governance in one command -- policy checks, PII scanning, and observability with zero code changes. - [Proxy Deployment Guide](https://waxell.ai/docs/observe/mcp-governance/proxy-deployment): Deploy the Waxell governance proxy with CLI, Docker, or docker-compose -- complete CLI reference, config file formats, and production considerations. - [Governing Third-Party MCP Providers](https://waxell.ai/docs/observe/mcp-governance/proxy-third-party): Use the Waxell governance proxy to add policy checks, PII scanning, and rug pull detection to third-party MCP providers like Composio, filesystem servers, and custom scripts. ### Architecture & Reference - [MCP Governance Architecture](https://waxell.ai/docs/observe/mcp-governance/architecture): Decision flowchart, deployment diagrams, and composability patterns for Waxell's three MCP governance products -- auto-instrumentor, server middleware, and governance proxy. - [MCP Governance API Reference](https://waxell.ai/docs/observe/mcp-governance/api-reference): Cross-product API reference for all MCP governance classes, functions, decorators, and configuration options across the auto-instrumentor, server middleware, and governance proxy. ## MCP Gateway > One governed front door for every MCP server your agents call ### MCP Gateway - [Waxell MCP Gateway: One Governed MCP Surface for Your Whole Company](https://waxell.ai/docs/mcp-gateway/overview): A single MCP endpoint your agents and AI tools connect to, brokering to 160+ upstream servers with policy, approvals, audit, and per-user identity on every call. - [Gateway Quickstart: Connect Claude in Two Minutes](https://waxell.ai/docs/mcp-gateway/quickstart): Connect Claude.ai, Claude Desktop, or Claude Code to the Waxell MCP Gateway and make your first governed tool call. - [Connect Microsoft Copilot Studio to the MCP Gateway](https://waxell.ai/docs/mcp-gateway/microsoft-copilot): Route a Copilot Studio agent's tool calls through the Waxell MCP Gateway with a Power Platform custom connector — shared API key or per-user OAuth, both governed and audited. - [Connector Catalog: 160+ Upstreams, Most with Zero Setup](https://waxell.ai/docs/mcp-gateway/catalog): Install MCP upstreams from the Waxell catalog, understand the Auto OAuth and Open badges, and connect user accounts. - [Upstream Authentication: From Fully Automatic to Bring-Your-Own](https://waxell.ai/docs/mcp-gateway/authentication): How the gateway authenticates to upstream MCP servers — MCP-spec OAuth with dynamic client registration, classic OAuth, open servers, API keys, and service accounts. ### Governance - [Policy Engine: Deny, Redact, Approve, Rate-Limit — Before the Call Happens](https://waxell.ai/docs/mcp-gateway/policies): The gateway's preventive policy engine — rule matching, actions, precedence, approval workflows, and notifications. - [Tool Management: Hundreds of Tools Without Drowning the Model](https://waxell.ai/docs/mcp-gateway/tool-management): Tool subsetting with scope tags, the find_tools and call_external_tool meta-tools, and per-user pinned tools. - [Security: Fingerprinting, Drift Defense, DLP, and the Audit Log](https://waxell.ai/docs/mcp-gateway/security): How the gateway defends against rug pulls and prompt injection in tool descriptions, scans for data leakage, and records everything durably. ### Operations - [Self-Hosting the Gateway In Your VPC](https://waxell.ai/docs/mcp-gateway/self-hosting): Run the MCP Gateway as a single-tenant deployment inside your own network while keeping the Waxell controlplane for policy and audit. - [Gateway Troubleshooting: Errors and What They Mean](https://waxell.ai/docs/mcp-gateway/troubleshooting): The errors you'll actually see from the MCP Gateway — what each means and how to fix it. ## Waxell Framework > Build governed agents — SDK primitives, tutorials, and workflows ### Getting Started - [Introduction](https://waxell.ai/docs/intro): The control plane for agentic systems. Add observability to existing agents or build governed agents from scratch. - [Installation](https://waxell.ai/docs/installation): Install and configure Waxell for your Python project. ### SDK - [SDK Overview](https://waxell.ai/docs/sdk/overview): Understanding the Waxell SDK - intent-only definitions for AI agents. - [@agent Decorator](https://waxell.ai/docs/sdk/agent-spec): Define agent containers with the @agent decorator. - [@workflow Decorator](https://waxell.ai/docs/sdk/workflow-spec): Define multi-step execution flows with the @workflow decorator — how steps become durable checkpoints and what ctx actually exposes. - [@tool Decorator](https://waxell.ai/docs/sdk/tool-spec): Integrate external systems with the @tool decorator. - [LLM Calls](https://waxell.ai/docs/sdk/decision-spec): How an agent calls a model in Waxell — ctx.llm.generate, routing hints, structured output, and tool-calling loops. ### Tutorials - [Evaluate the Runtime, End to End](https://waxell.ai/docs/tutorials/evaluate-the-runtime): A guided walk through the public runtime-evaluation project — five frameworks against one domain on your laptop, verified end-user and agent identity, a policy block, evaluations, signed evidence, and four memory tiers. - [Build Your First Agent](https://waxell.ai/docs/tutorials/first-agent): Step-by-step tutorial to build your first Waxell agent. - [Multi-Step Workflows](https://waxell.ai/docs/tutorials/workflows): Build multi-step workflows with branching, composition, and error handling — on the real runtime API. - [Adding Governance](https://waxell.ai/docs/tutorials/governance): Control and audit agent behaviour — per-agent limits, approvals, policy evaluation points, and the audit trail. - [Deploying to Production](https://waxell.ai/docs/tutorials/production): Deploy Waxell agents to production environments. ## Waxell Runtime > Run governed agents in production — execution tiers, isolation, working memory, and durable workflows ### Waxell Runtime - [Quickstart](https://waxell.ai/docs/runtime/quickstart): Build, register, and run your first Waxell agent in under five minutes. - [Your First Agent with wax init](https://waxell.ai/docs/runtime/getting-started-wax-init): Scaffold, deploy, and run a governed Claude agent on the Waxell runtime in about five minutes — wax init, wax push, wax signals fire. - [Evaluate the Runtime, End to End](https://waxell.ai/docs/tutorials/evaluate-the-runtime): A guided walk through the public runtime-evaluation project — five frameworks against one domain on your laptop, verified end-user and agent identity, a policy block, evaluations, signed evidence, and four memory tiers. - [Runtime Overview](https://waxell.ai/docs/runtime/overview): Understanding the Waxell Runtime - the execution engine for AI agents. - [How the Runtime Works](https://waxell.ai/docs/runtime/how-it-works): What actually happens between a signal arriving and a run finishing — routing, governance, execution, telemetry, and cost attribution. - [waxell.yaml Reference](https://waxell.ai/docs/runtime/waxell-yaml-reference): Complete field reference for the waxell.yaml agent specification file. - [Framework Support for Manifest Agents](https://waxell.ai/docs/runtime/framework-support): What each framework value in waxell.yaml gives you on the hosted Waxell runtime — how the agent executes, which tools it can call, and which caps apply. - [Ship a Claude Agent to Your Team](https://waxell.ai/docs/runtime/ship-claude-agent): Take a claude_agent_sdk / Claude Code agent you built locally and publish it to Waxell so your whole team can use it in prod — governed, observable, and per-user. - [Build & Push a Custom Tool](https://waxell.ai/docs/runtime/custom-tools): Write a custom tool, declare it in waxell.yaml, and wire it into an agent so the whole team's agents can call it. - [Register a Domain](https://waxell.ai/docs/runtime/domains): Register a domain so your agents can call back into your own app — ctx.domain("company", "get", ...) routed to your HTTPS endpoints, with per-end-user identity and governance. - [Verifying End-User Tokens in Your Service](https://waxell.ai/docs/runtime/verify-end-user-tokens): When a Waxell agent calls your domain endpoint on behalf of one of your users, it sends a short-lived Ed25519-signed token. Verify it against your workspace's JWKS and authorize on its claims. - [Verifying Agent Identity (AXID)](https://waxell.ai/docs/runtime/verify-agent-identity): Every governed run carries a signed Agent Execution Identity. Each domain call presents it on X-Waxell-AXID — which agent, which version, which run, for which person, delegated by which parent — verifiable offline against your workspace's JWKS. - [Signal HTTP Reference](https://waxell.ai/docs/runtime/signals-http-reference): Fire a signal at your agents over HTTP, then follow the run it starts by polling its event log or subscribing to a Server-Sent Events stream. - [Operating Agents](https://waxell.ai/docs/runtime/operating-agents): Run agents on a schedule, watch them live, replay runs, get alerted on failures, and tune runtime settings without redeploying. - [Execution Context](https://waxell.ai/docs/runtime/execution-context): What ctx gives your agent at runtime — calling your application, the LLM, tools, memory, secrets, and pausing for humans. - [Execution Tiers](https://waxell.ai/docs/runtime/execution-tiers): Choose where your agents run — shared workers, dedicated warm slots, or a self-contained container built from your own dependencies. Same governance, same telemetry, same audit trail at every tier. - [Trial, limits & errors](https://waxell.ai/docs/runtime/trial-and-limits): What the runtime trial includes, the limits every plan enforces at execution start, and what each structured error means. - [Working Memory](https://waxell.ai/docs/runtime/working-memory): The Waxell runtime's memory tiers (working, session, episodic, semantic) — how domain results are captured to a scratchpad, referenced via $ref handles, and isolated per tenant. - [Graph Memory](https://waxell.ai/docs/runtime/graph-memory): Governed knowledge graphs as an agent memory tier — named graphs per workspace, per-agent grants, provenance on every node, visibility groups, and the tools agents use to read and write them. - [Your own data plane](https://waxell.ai/docs/runtime/data-plane): Run a workspace from its own Postgres, Redis and object store — full data ownership for regulated or sovereignty-bound teams. - [Durable Execution](https://waxell.ai/docs/runtime/workflow-envelope): How Waxell checkpoints a run so it can survive a crash and resume — what's a checkpoint, what a run's states mean, and which ones are terminal. - [Backends](https://waxell.ai/docs/runtime/backends): Configure runtime backends for different environments. ## Managed Runtimes > Run Waxell-governed agents on third-party agent runtimes ### Runtimes - [Runtimes — Deploy Waxell where your agents run](https://waxell.ai/docs/runtimes/overview): One-stop guide for shipping Waxell-governed agents to managed agent runtimes (Amazon Bedrock AgentCore, IBM watsonx.ai, Azure AI Foundry, Vertex AI Agent Engine, and more). Pick your runtime, ship in 5 minutes. - [Amazon Bedrock AgentCore Runtime (BYO code)](https://waxell.ai/docs/runtimes/bedrock-agentcore): Deploy a Waxell-instrumented Python agent to Amazon Bedrock AgentCore Runtime. The SDK ships inside the microVM and produces full client-side spans plus policy enforcement — same behavior as deploying your agent to any other Python host. 5-minute deploy. - [IBM watsonx.ai](https://waxell.ai/docs/runtimes/watsonx): Wrap your IBM watsonx.ai Python agent with Waxell — every Granite, Llama, and Mistral call on watsonx Foundation Models shows up in your governance dashboard with token counts and IBM-published cost. 5-minute deploy. - [Azure AI Foundry (hosted agents)](https://waxell.ai/docs/runtimes/azure-ai-foundry): Deploy a Waxell-instrumented LangGraph agent to Azure AI Foundry as a hosted agent. The SDK ships inside the container and produces full client-side spans plus in-path policy enforcement — runs stream natively into Waxell with no App Insights pull. 5-minute deploy. - [Vertex AI Agent Engine](https://waxell.ai/docs/runtimes/vertex-agent-engine): Deploy a Waxell-instrumented LangGraph agent to Vertex AI Agent Engine. No Dockerfile — you hand Agent Engine a Python object, waxell-observe ships as a requirements entry, and every run's full span trace streams natively into your Waxell dashboard. 5-minute deploy. ## Agent Connections > Connect third-party and self-hosted agents to Waxell governance ### Developer MCP - [For Coding Agents](https://waxell.ai/docs/agents/overview) - [Setup](https://waxell.ai/docs/agents/setup) - [Connect via OAuth](https://waxell.ai/docs/agents/mcp-connection): Connect Claude Desktop or Claude Code to Waxell using OAuth — no API keys in config files. - [Capabilities](https://waxell.ai/docs/agents/capabilities) - [Self-Hosting](https://waxell.ai/docs/agents/self-hosting) - [Managing Connections](https://waxell.ai/docs/agents/managing-connections): View, revoke, and regenerate MCP OAuth connections in the Waxell dashboard. - [OAuth Flow](https://waxell.ai/docs/agents/oauth-flow): How the MCP OAuth authorization flow works — discovery, client registration, PKCE authorization, and token exchange. ## Waxell Connect > Workspaces, governance, and Slack for human-agent collaboration ### Connect - [Connect — Third-Party Agent Visibility](https://waxell.ai/docs/connect/overview) - [Connect Workspaces](https://waxell.ai/docs/connect/workspaces) - [Connect Agent Governance](https://waxell.ai/docs/connect/governance): How Waxell governs external AI agents (Claude Code, Claude Cowork, Codex, MCP) connected via the Connect platform — enforcement models, scope dimensions, lifecycle, and policy categories. - [Connect Slack Integration](https://waxell.ai/docs/connect/slack-integration) ## Waxell Endpoints > Endpoint visibility and on-device guard for AI tools your team already uses ### Get Started - [Waxell Endpoints — Govern the AI on Every Machine](https://waxell.ai/docs/endpoints/overview): Waxell Endpoints brings the AI tools running on your team's laptops — Claude Desktop, Cursor, Claude Code, Copilot, ChatGPT, browsers — under discovery, observability, and governance. Start with shadow-AI visibility, opt into capture per host. - [How Waxell Endpoints Works](https://waxell.ai/docs/endpoints/how-it-works): The architecture behind Waxell Endpoints — the desktop agent's components, how it enrolls against a per-tenant CA, what it observes vs. captures, and how on-device DLP keeps raw payloads from ever leaving the machine. - [Key Concepts & Glossary](https://waxell.ai/docs/endpoints/concepts): The vocabulary of Waxell Endpoints — device enrollment, tenant CA, AI apps, app types and capture ceiling, metadata flows vs. payload capture, the Guard cascade, and the device→agent map. ### Deploy to a Fleet (MDM) - [Deploy to a Fleet (MDM) — Overview](https://waxell.ai/docs/endpoints/mdm/overview): How Waxell deploys the desktop endpoint agent to a whole fleet via any MDM — one per-tenant profile plus the signed installer, silent enrollment, capture off by default. - [Deploy to a Mac Fleet (MDM)](https://waxell.ai/docs/endpoints/mdm/macos): Step-by-step — push the Waxell tenant profile and signed .pkg from Hexnode, Jamf, Kandji, or Intune so every managed Mac silently enrolls, trusts the tenant CA, and reports its AI apps. - [Deploy to a Windows Fleet (Intune)](https://waxell.ai/docs/endpoints/mdm/windows): Step-by-step — push the Waxell trusted cert, managed-config script, and agent MSI from Intune so every managed PC enrolls, trusts the tenant CA, and reports its AI apps. Includes Memory Integrity (HVCI) guidance. ### Single Machine (No MDM) - [Install on One Machine (No MDM)](https://waxell.ai/docs/endpoints/manual-install): Step-by-step guide to installing the Waxell desktop agent on a single Mac or Windows machine yourself — no MDM, no IT. Download, sign in, approve the network monitor, and start seeing your AI apps. ### Guard — Capture & Control - [The Guard Cascade](https://waxell.ai/docs/endpoints/guard/overview): Guard is the layered policy that controls what the Waxell agent observes, blocks, or captures on each device. Understand the Global → App type → User group → Device → Agent cascade, how layers override field by field, and the resolve simulator. - [Enabling Capture (Creating a Guard)](https://waxell.ai/docs/endpoints/guard/enable-capture): Step-by-step — how to turn payload capture on for a specific AI host using the Waxell Guard cascade, scope it to an app type, group, or device, and verify it with the resolve simulator. Capture stays off until you do this. - [Privacy & On-Device DLP](https://waxell.ai/docs/endpoints/guard/privacy-and-dlp): What payload capture does and doesn't expose — capture is off by default, limited to catalog AI hosts, never banking/health/mail, and DLP-redacted on the device so raw payloads never leave the machine. ### Reference - [What Gets Installed](https://waxell.ai/docs/endpoints/reference/what-gets-installed): Reference — every component the Waxell desktop endpoint agent installs on macOS and Windows, what each one does, and where its files and logs live. - [Troubleshooting & Diagnostics](https://waxell.ai/docs/endpoints/reference/troubleshooting): Fixes for common Waxell desktop endpoint agent issues on macOS and Windows — system-extension approval, SmartScreen, Defender, browser sign-in, Memory Integrity (HVCI), and where to find logs. ## Platform > Billing, insights, and reseller administration ### Platform - [Insights — Executive Intelligence](https://waxell.ai/docs/platform/insights) - [Billing & Subscription Management](https://waxell.ai/docs/platform/billing) - [Partner & Reseller Program](https://waxell.ai/docs/platform/reseller) ## CLI > The wax command-line interface ### CLI - [CLI Reference](https://waxell.ai/docs/reference/cli): The complete guide to the wax CLI — authenticate, push agents, explore runs and traces, govern, and configure Waxell from your terminal. ## Guides > Task-oriented walkthroughs ### Guides - [Architecture](https://waxell.ai/docs/guides/architecture): Deep dive into Waxell's data flow and security architecture. - [Enterprise Guide](https://waxell.ai/docs/guides/enterprise): Configure enterprise security features including data residency, sub-tenants, and compliance. - [Best Practices](https://waxell.ai/docs/guides/best-practices): Patterns for production-ready Waxell agents — scoping, checkpointing, prompting, governance, testing, and what to monitor. ### Reference - [CLI Reference](https://waxell.ai/docs/reference/cli): The complete guide to the wax CLI — authenticate, push agents, explore runs and traces, govern, and configure Waxell from your terminal. - [Enterprise API](https://waxell.ai/docs/reference/enterprise-api): API reference for enterprise features including data residency, sub-tenants, and compliance. ## Migrating to Waxell > Move from other observability and agent platforms ### Framework Comparison - [LangChain vs Waxell](https://waxell.ai/docs/migrate/langchain-vs-waxell): Side-by-side comparison of LangChain alone, LangChain with Waxell Observe, and native Waxell for building AI agents. - [CrewAI vs Waxell](https://waxell.ai/docs/migrate/crewai-vs-waxell): Side-by-side comparison of CrewAI alone, CrewAI with Waxell Observe, and native Waxell for building AI agents. - [Feature Comparison Matrix](https://waxell.ai/docs/migrate/feature-matrix): Comprehensive feature comparison across LangChain, CrewAI, custom Python agents, Waxell Observe, and Waxell Native. ### Migration Path - [Progressive Migration](https://waxell.ai/docs/migrate/overview): A phased approach to adopting Waxell. Each phase delivers standalone value -- you can stop at any phase. - [Phase 1: Add Observability](https://waxell.ai/docs/migrate/phase-1-observe): Add observability, cost tracking, and policy enforcement to your existing AI agents with waxell-observe. - [Phase 2: Add Signals](https://waxell.ai/docs/migrate/phase-2-signals): Move from ad-hoc agent triggering to webhook-driven execution with Waxell signals. - [Phase 3: Agent Builder](https://waxell.ai/docs/migrate/phase-3-agent-builder): AI-assisted migration tool that converts existing agents to native Waxell SDK definitions. - [Phase 4: Go Fully Native](https://waxell.ai/docs/migrate/phase-4-native): Manual migration guide for converting existing agents to native Waxell SDK definitions with full governance and durable workflows. ## agentDiscovery ### Agent Discovery - [Agent Discovery: See and Govern Every AI Agent Across Your Estate](https://waxell.ai/docs/agent-discovery/overview): Connect the platforms your teams build agents on — Microsoft, Google, AWS, Hatz AI, Glean, Devin, n8n, UiPath and more — and Waxell inventories every agent, pulls its activity, and shows exactly how governed each one is. Read-only by default. - [Agent Discovery Connector Catalog — Every Supported Platform](https://waxell.ai/docs/agent-discovery/connectors): Every platform Agent Discovery connects to — what Waxell discovers on each, how you connect it, and whether Waxell can pull activity, write governance policy, or sit in the request path. - [Connect Hatz AI — Discover Agents Across Every Customer Tenant](https://waxell.ai/docs/agent-discovery/hatz-ai): Paste one Hatz AI MSP key and Waxell inventories the agents, apps and workflows across every customer tenant you manage — with per-customer usage, users and models. Read-only; chat content is never stored. - [Connect Microsoft — Discover Copilot & Foundry Agents](https://waxell.ai/docs/agent-discovery/microsoft): One Global-Admin consent click connects your Microsoft tenant. Waxell discovers every M365 Copilot, Copilot Studio, and Azure AI Foundry agent across your environments — read-only, no app registration, no secret. - [Connect Google Cloud — Discover Vertex & Gemini Enterprise Agents](https://waxell.ai/docs/agent-discovery/google): Grant Waxell's service account a read-only role and Waxell discovers your Vertex AI Agent Engine, Conversational Agents, and Gemini Enterprise apps — keyless, no service-account key to download or paste. - [Connect AWS — Discover Bedrock AgentCore Agents](https://waxell.ai/docs/agent-discovery/aws): Launch one CloudFormation stack and Waxell discovers your Bedrock AgentCore runtimes and their activity — a read-only cross-account role gated by an External ID, no credentials leave your account. Scales to a whole AWS Organization. - [Connect SaaS AI Platforms — Glean, Rovo, ServiceNow, Devin, n8n, UiPath and More](https://waxell.ai/docs/agent-discovery/saas-connectors): Step-by-step setup for every SaaS connector in Agent Discovery — the credential each one needs, the read-only scope to grant, and what Waxell discovers. Assistants, agent builders, workflow and RPA tools, code repositories and observability. ## sso ### Get Started - [Single Sign-On, SCIM and Directory Sync](https://waxell.ai/docs/sso/overview): Sign in to Waxell with Microsoft Entra, Okta, Google Workspace or any SAML 2.0 / OIDC identity provider. Provision and deprovision people automatically with SCIM or directory sync, map IdP groups to roles and teams, and enforce SSO per workspace. - [SSO Quickstart](https://waxell.ai/docs/sso/quickstart): Set up single sign-on for a Waxell workspace in about ten minutes, with Microsoft Entra, Okta, Google Workspace or any SAML 2.0 / OIDC identity provider. ### Identity Providers - [SSO with Microsoft Entra ID (Azure AD)](https://waxell.ai/docs/sso/entra): Step-by-step SAML 2.0 single sign-on between Microsoft Entra ID (formerly Azure AD) and Waxell, including group claims, directory sync and SCIM. - [SSO with Okta](https://waxell.ai/docs/sso/okta): Connect Okta to Waxell with OIDC or SAML 2.0, send groups for role mapping, and provision users with Okta's SCIM integration or directory sync. - [SSO with Google Workspace](https://waxell.ai/docs/sso/google): Sign in to Waxell with Google Workspace accounts using OIDC, and sync users and groups (including nested groups) from the Google Admin directory. - [SSO with Any SAML 2.0 or OIDC Provider](https://waxell.ai/docs/sso/other-providers): Connect Waxell to OneLogin, JumpCloud, Ping, Auth0, Keycloak, ADFS or any SAML 2.0 / OpenID Connect identity provider. The exact URLs, attributes and claims Waxell expects. ### Who Gets In - [Creating Accounts on First Sign-In (JIT)](https://waxell.ai/docs/sso/account-creation): Let anyone in your identity provider get a Waxell account the first time they sign in with SSO, or keep SSO for existing members only. - [Roles, Teams and Group Mapping](https://waxell.ai/docs/sso/group-mapping): Map identity-provider groups to Waxell roles and teams at sign-in, and set a default role and team for everyone else. - [SCIM 2.0 Provisioning](https://waxell.ai/docs/sso/scim): Let Okta, Microsoft Entra or any SCIM 2.0 client create, update and deprovision Waxell users and teams. Deprovisioning revokes sessions, API keys and device ownership. - [Directory Sync (Google Workspace, Okta, Microsoft Entra)](https://waxell.ai/docs/sso/directory-sync): Pull users and groups from Google Workspace, Okta, Microsoft Entra or JumpCloud into Waxell, choose whether to create accounts, and offboard people your directory removes. - [People and Email Addresses](https://waxell.ai/docs/sso/people): Waxell treats one person with several email addresses as one person, across sign-in, endpoint activity, user counts and guards. ### Security - [Multi-Factor Authentication with SSO](https://waxell.ai/docs/sso/mfa): How Waxell MFA interacts with single sign-on, and how to accept your identity provider's MFA so people aren't challenged twice. - [Enforcing SSO](https://waxell.ai/docs/sso/enforce): Require single sign-on for your email domains on a Waxell workspace. What enforcement turns off, what it doesn't, and how to roll it out safely. - [Owner Recovery When Your IdP Is Down](https://waxell.ai/docs/sso/owner-recovery): How a Waxell workspace owner gets back in with a time-limited recovery link when SSO is enforced and the identity provider is unavailable. - [Offboarding](https://waxell.ai/docs/sso/offboarding): What Waxell revokes when someone is removed from a workspace through the Users page, SCIM or directory sync. - [Identity and Sign-In Audit Log](https://waxell.ai/docs/sso/audit): Where Waxell records SSO sign-ins, failures, recovery links, OAuth, SCIM and directory events. ### Reference - [SSO Troubleshooting](https://waxell.ai/docs/sso/troubleshooting): Every Waxell SSO error code, what causes it, and how to fix it. - [SSO Reference](https://waxell.ai/docs/sso/reference): Every Waxell SSO, SAML, OIDC, SCIM and directory URL, and every identity-provider setting.