Recommend pipx for AgentOps Toolkit installation to avoid dependency conflicts #102

Summary

The current installation instructions recommend installing agentops-toolkit inside a project's virtual environment using pip install. This causes pip dependency conflicts because agentops-toolkit pins different versions of shared packages (e.g., azure-ai-projects>=2.0.1, pydantic>=2, openai>=2.8.0) than what the target project may require.

This was observed in the GPT-RAG Orchestrator where azure-ai-projects==2.0.0b3 conflicts with agentops-toolkit's >=2.0.1 requirement, along with version mismatches in starlette, multidict, propcache, and regex.

Problem

Since agentops-toolkit is a CLI tool (the agentops command) and not a library imported by application code, it should not share a virtual environment with the target project. Installing it inside a project venv will always risk dependency conflicts.

Proposed Solution: Use pipx

pipx installs Python CLI tools in isolated virtual environments while making the agentops command available globally. Zero dependency conflicts, regardless of the target project's requirements.

Installation (one-time setup)

# Install pipx (if not already installed)
pip install pipx
pipx ensurepath

# Install AgentOps Toolkit (isolated from any project)
pipx install agentops-toolkit

# Verify
agentops --version

Upgrade

pipx upgrade agentops-toolkit

Usage (works in any project, any directory)

agentops eval run
agentops config show

Alternative: pip install (with warning)

For users who prefer pip install, the docs should include a warning:

Warning: Installing agentops-toolkit inside a project's virtual environment may cause dependency conflicts. If you experience version mismatches, use pipx install agentops-toolkit instead.

Acceptance Criteria

• Installation docs recommend pipx as the primary installation method
• pip install in a project venv is documented as an alternative with a clear warning about potential dependency conflicts
• Cross-platform pipx installation instructions are provided (Windows, macOS, Linux)
• Update all VS Code extension skills (agentops-eval, agentops-config, agentops-dataset, agentops-report, agentops-regression, agentops-trace, agentops-monitor, agentops-workflow, and any others referencing installation) to use pipx install agentops-toolkit instead of pip install agentops-toolkit in their installation/prerequisite guidance