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

Log an event to an active AgentLens session.

End an active AgentLens monitoring session.

Query events from an AgentLens session.

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

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.

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".

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.

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.

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.

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"] })

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.

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 })

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" } })

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 })

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 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" })

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" })

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" })