Installation
Install AgentOps and the Xpander SDK, along with the required dependencies:Setting Up API Keys
Youβll need API keys for AgentOps, Xpander, and OpenAI:- AGENTOPS_API_KEY: From your AgentOps Dashboard
- XPANDER_API_KEY: From your Xpander Dashboard
- XPANDER_AGENT_ID: The ID of your Xpander agent
- OPENAI_API_KEY: From the OpenAI Platform
.env
file:
xpander_config.json
file:
Quick Start
The key to AgentOps + Xpander integration is initialization order: Initialize AgentOps before importing the Xpander SDK to enable automatic instrumentation.The following example shows the callback-based integration pattern. For a complete working example, see our Xpander example.
Whatβs Automatically Tracked
AgentOps automatically captures comprehensive telemetry from your Xpander agents:π€ Agent Activities
- Agent initialization and configuration
- Task lifecycle (start, execution steps, completion)
- Workflow phase transitions (planning β executing β finished)
- Session management and context persistence
π§ LLM Interactions
- All OpenAI API calls with full request/response data
- Token usage and cost tracking across models
- Conversation history and context management
- Model parameters and settings
π οΈ Tool Executions
- Tool call detection with parameters and arguments
- Tool execution results and success/failure status
- Tool performance metrics and timing
- Tool call hierarchies and dependencies
π Performance Metrics
- End-to-end execution duration and timing
- Step-by-step workflow progression
- Resource utilization and efficiency metrics
- Error handling and exception tracking
Key Features
β Zero-Configuration Setup
No manual trace creation or span management required. Simply initialize AgentOps before importing Xpander SDK.β Complete Workflow Visibility
Track the entire agent execution flow from task initiation to completion, including all intermediate steps.β Real-time Monitoring
View your agent activities in real-time on the AgentOps dashboard as they execute.β Tool Execution Insights
Monitor which tools are being called, their parameters, execution time, and results.β Cost Tracking
Automatic token usage tracking for all LLM interactions with cost analysis.Callback Handler Pattern
The Xpander integration supports two main patterns:- Direct Integration: Directly instrument your agent code (shown above)
- Callback Handler: Use XpanderEventListener for webhook-style integration
- Production deployments with centralized monitoring
- Multi-agent orchestration systems
- Event-driven architectures
Runtime-Specific Instrumentation
Xpander SDK uses JSII to create methods at runtime, which requires specialized instrumentation. AgentOps handles this automatically by:- Method Wrapping: Dynamically wrapping agent methods as theyβre created
- Context Persistence: Maintaining session context across runtime object lifecycle
- Agent Detection: Automatically detecting and instrumenting new agent instances
- Tool Result Extraction: Properly extracting results from JSII object references
Troubleshooting
Import Order Issues
If youβre not seeing traces, ensure AgentOps is initialized before importing Xpander SDK:Missing Tool Results
If tool results show{"__jsii_ref__": "..."}
instead of actual content, ensure youβre using the latest version of AgentOps, which includes improved JSII object handling.
Import Errors (E402)
If you see linting errors about imports not being at the top of the file, this is expected for Xpander integration. Add# ruff: noqa: E402
at the top of your file to suppress these warnings, as the import order is required for proper instrumentation.