AgentLens

List, inspect, and manage AgentLens agents. **When to use:** To see which agents are registered, check agent details and error rates, or unpause a paused agent. **Actions:** - `list`: List all agents with error rates - `detail`: Get agent detail by ID - `unpause`: Clear paused state for an agent **Example:** agentlens_agents({ action: "list" })

Manage alert rules and view alert history. **When to use:** To create alerting rules for error rates, costs, or latency thresholds; manage existing rules; or review past alert triggers. **Actions:** - `list`: List all alert rules - `create`: Create a new alert rule - `update`: Update an existing alert rule - `delete`: Delete an alert rule - `history`: View recent alert triggers **Example:** agentlens_alerts({ action: "create", name: "High error rate", condition: "error_rate_above", threshold: 0.1, windowMinutes: 60 })

Query operational analytics: metrics, costs, agent performance, and tool usage. **When to use:** To understand system performance trends, cost breakdowns, agent activity, or tool usage patterns over time. **Actions:** - `metrics`: Get bucketed metrics with optional range/date filters - `costs`: Get cost breakdown - `agents`: Get per-agent metrics - `tools`: Get tool usage statistics **Example:** agentlens_analytics({ action: "metrics", range: "24h" })

Manage A/B benchmarks: create, list, check status, get results, and control lifecycle. **When to use:** To set up controlled experiments comparing different agent configurations (models, prompts, parameters), track which variant performs better, and get statistical results. **Workflow:** 1. `create` — Define a benchmark with 2+ variants and metrics 2. Tag sessions with variant tags during data collection 3. `start` — Transition benchmark to running 4. `status` — Check progress (session counts per variant) 5. `results` — Get statistical comparison with p-values 6. `complete` — Finalize the benchmark **Actions:** - `create`: Set up a new benchmark (name, variants[], metrics[]) - `list`: List benchmarks, optionally filter by status - `status`: Get benchmark detail with per-variant session counts - `results`: Get formatted comparison table with statistical analysis - `start`: Transition benchmark to running state - `complete`: Transition benchmark to completed state **Example:** agentlens_benchmark({ action: "create", name: "GPT-4o vs Claude", variants: [{name: "gpt4o", tag: "v-gpt4o"}, {name: "claude", tag: "v-claude"}], metrics: ["cost", "latency", "success_rate"] })

Retrieve cross-session context for a topic — related session summaries and lessons ranked by relevance. **When to use:** At the start of a session to load relevant history, when building a system prompt with past experience, when starting work on a topic the agent has handled before, or to audit what happened with a specific topic. **What it returns:** Related sessions (with summaries, key events, and relevance scores) and related lessons, all ranked by relevance to the topic. Includes an overall summary. **Example:** agentlens_context({ topic: "database migrations", limit: 5 }) → returns past sessions about DB migrations with key events, plus any lessons learned about migrations.

Manage cost budgets and anomaly detection. **When to use:** To create/manage spending limits, check budget utilization, or configure cost anomaly detection. **Actions:** - `list`: List all cost budgets - `create`: Create a new budget - `update`: Update an existing budget - `delete`: Delete a budget - `status`: Check spend vs limit for a budget - `anomaly_config`: Get anomaly detection configuration - `anomaly_update`: Update anomaly detection settings **Example:** agentlens_cost_budgets({ action: "create", scope: "global", period: "daily", limitUsd: 10, onBreach: "alert" })

Delegate a task to another agent in the AgentLens network. **When to use:** When you've discovered an agent capable of handling a specific task (via agentlens_discover) and want to delegate work to it. **Example:** agentlens_delegate({ action: "delegate", targetAgentId: "anon-abc123", taskType: "translation", input: { text: "Hello", targetLang: "es" } })

Discover available agent capabilities in the network. **When to use:** Before delegating a task, to find agents that can handle a specific task type. Returns ranked results with trust scores, estimated cost, and latency. **Example:** agentlens_discover({ action: "discover", taskType: "code-review", minTrustScore: 70, limit: 5 })

Check guardrail status for the current agent. Returns active guardrail rules, their current state, and recent trigger history. **When to use:** To check what guardrails are protecting this agent, whether any have been triggered recently, and what conditions/actions are configured. **What it returns:** A list of configured guardrail rules with their status (enabled/disabled, trigger count, last trigger time) and recent trigger history. **Example:** agentlens_guardrails({}) → returns all guardrail rules and their status.

Check the health score of the current agent. Returns overall score (0-100), trend, and dimension breakdown. **When to use:** To assess the current health and performance of the agent, to check if error rates or latency are degrading, or to get a quick overview of agent reliability metrics. **What it returns:** An overall health score (0-100), a trend indicator (improving/stable/degrading), and a breakdown by five dimensions: error rate, cost efficiency, tool success, latency, and completion rate. **Example:** agentlens_health({ window: 7 }) → returns health score with dimension breakdown for the last 7 days.

Log an event to an active AgentLens session.

Log a complete LLM call (request + response) to an active AgentLens session. Emits paired llm_call and llm_response events.

Get cost optimization recommendations. Analyzes LLM call patterns and suggests cheaper model alternatives. **When to use:** To identify cost-saving opportunities by switching expensive models to cheaper alternatives for tasks that don't require the most capable model. Analyzes call complexity (simple/moderate/complex) and success rates. **What it returns:** A list of model switch recommendations with estimated monthly savings, confidence levels, and success rate comparisons. Sorted by potential savings. **Example:** agentlens_optimize({ period: 7 }) → returns recommendations like "Switch gpt-4o → gpt-4o-mini for SIMPLE tasks, saving $89/month".

Manage prompt templates and versions. **Actions:** - `list`: List prompt templates (optional category, search filters) - `get`: Get a template with all versions by ID - `create`: Create a new prompt template with initial content - `update`: Create a new version of an existing template - `analytics`: Get per-version metrics for a template - `fingerprints`: List auto-discovered prompt fingerprints **Example:** agentlens_prompts({ action: "list", category: "system" })

Query events from an AgentLens session.

Analyze behavioral patterns from agent sessions — error patterns, tool sequences, cost analysis, and performance trends. **When to use:** To identify recurring errors and their root causes (error_patterns), to understand cost drivers and optimize model usage (cost_analysis), to discover common tool usage chains and their success rates (tool_sequences), or to track performance over time (performance_trends). **What it returns:** A list of structured insights with type, summary, data, and confidence score, plus metadata about how many sessions/events were analyzed. Each analysis type returns different data shapes. **Example:** agentlens_reflect({ analysis: "error_patterns", agentId: "my-agent", from: "2026-01-01" }) → returns recurring error patterns with counts, first/last seen, and affected sessions.

Replay a past session as a structured, human-readable timeline. **When to use:** To review what happened in a previous session — understand failures, decision patterns, timing, or cost accumulation. Great for debugging or post-mortem analysis. **What it returns:** A session header (agent, status, duration, cost, event counts) followed by numbered, timestamped steps with event type icons and context annotations. **Parameters:** - sessionId (required): The session to replay - fromStep/toStep: Replay a specific step range - eventTypes: Comma-separated filter (e.g., "llm_call,tool_call") - summaryOnly: Set true to get just the summary header (fast for large sessions) **Example:** agentlens_replay({ sessionId: "ses_abc123", summaryOnly: true }) → returns session summary without steps.

End an active AgentLens monitoring session.

Start a new AgentLens monitoring session. Returns a sessionId to use for subsequent events.

Browse and inspect AgentLens sessions. **When to use:** To find past sessions, inspect session details, or view a timeline of events within a session. Useful for debugging, auditing, or reviewing agent activity. **Actions:** - `list`: List sessions with optional filters (agentId, status, date range, tags) - `detail`: Get full session detail with aggregates - `timeline`: Get timestamped event list for a session **Example:** agentlens_sessions({ action: "list", agentId: "my-agent", status: "completed", limit: 10 })

Get storage statistics and system overview metrics. **When to use:** To check database/storage utilization or get a high-level system overview. **Actions:** - `storage`: Get storage stats (database size, event counts, etc.) - `overview`: Get overview metrics (active sessions, agents, recent activity) **Example:** agentlens_stats({ action: "storage" })

Get trust scores for agents. **When to use:** To check the trust/reliability score of an agent before delegating tasks or to monitor agent reputation. **Actions:** - `score`: Get trust score for a specific agent **Example:** agentlens_trust({ action: "score", agentId: "my-agent" })