Argus Panoptes

百眼巨人

您的AI代理的全视之眼。

Argus Panoptes是一个用于AI代理框架的自托管、统一的可观察性平台。它跟踪LangGraph、CrewAI、OpenAI代理SDK、Google ADK、AutoGen、PydanticAI以及任何发布OpenTetry GenAI跨度的框架的性能、成本和行为。

阿格斯以希腊神话中的百眼巨人命名，他注视着每一个特工、每一个踪迹、每一枚代币、每一美元——没有什么能逃过他的目光。

特性

• 与框架无关的摄入 --通过REST API接受OpenTelemetry GenAI语义约定v1.37版本
• 成本跟踪 --OpenAI、Anthropic、Google、DeepSeek、xAI、Mistral和Meta模型的自动每个令牌成本计算
• 实时仪表盘 --通过服务器发送事件（SSE）实时更新指标，使用HTMX+Alpine.js构建
• 跟踪可视化 --具有span树渲染的可搜索跟踪资源管理器
• 可配置的警报 --基于规则的警报和webhook通知（Slack等）
• 热重载配置 --编辑 config/argus.yaml 更改实时生效，零停机时间
• 双数据库支持 --SQLite用于开发，PostgreSQL用于生产，相同的代码库
• API密钥验证 --用于摄入端点的可选API密钥身份验证
• 速率限制 --可配置的每客户端摄取速率限制
• 轻量级前端 --HTMX+Alpine.js+顺风CSS，无需js构建步骤，总js不超过31KB

快速开始

Docker（推荐）

# Clone the repository
git clone https://github.com/aj-geddes/argus-panoptes.git
cd argus-panoptes

# Start with Docker Compose (development mode with hot-reload)
cd docker
docker compose up

# Open the dashboard
open http://localhost:8000

Docker（生产）

# Build the production image
docker build -t argus-panoptes -f docker/Dockerfile .

# Run with default SQLite
docker run -p 8000:8000 argus-panoptes

# Run with PostgreSQL
docker run -p 8000:8000 \
  -e DATABASE_URL="postgresql+asyncpg://user:pass@db-host:5432/argus" \
  -e ARGUS_API_KEY="your-secret-key" \
  argus-panoptes

本地开发

# Prerequisites: Python 3.12+
python -m venv .venv
source .venv/bin/activate

# Install with development dependencies
pip install -e ".[dev]"

# Run the development server
uvicorn argus.main:app --reload --reload-dir src

# Open the dashboard
open http://localhost:8000

配置

所有配置都存在 config/argus.yaml 并且是 热重新加载 --编辑文件并立即应用更改，而无需重新启动服务器。

复制示例配置以开始：

cp config/argus.example.yaml config/argus.yaml

数据库

database:
  # SQLite for development (default):
  url: "sqlite+aiosqlite:///./argus.db"

  # PostgreSQL for production:
  # url: "postgresql+asyncpg://user:pass@localhost:5432/argus"

  pool_size: 10

您还可以通过以下方式设置数据库URL DATABASE_URL 环境变量。

安全

security:
  api_key_auth:
    enabled: true
    header_name: "X-API-Key"
    key: "your-secret-api-key"  # Or set ARGUS_API_KEY env var
  rate_limiting:
    enabled: true
    requests_per_window: 1000
    window_seconds: 60

成本模型

令牌定价按提供商、每种型号（每百万个令牌）配置：

cost_model:
  providers:
    openai:
      gpt-5.4: { input: 2.50, output: 10.00 }
    anthropic:
      claude-opus-4-6: { input: 5.00, output: 25.00 }

警报

alerts:
  enabled: true
  rules:
    - name: "High error rate"
      condition: "error_rate > 0.10"
      window: "5m"
      severity: "critical"
      notify: ["webhook"]

API

摄入

将OpenTetry GenAI跨度发送到摄入端点：

curl -X POST http://localhost:8000/v1/traces \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "resourceSpans": [{
      "resource": {
        "attributes": [
          {"key": "gen_ai.agent.name", "value": {"stringValue": "my-agent"}}
        ]
      },
      "scopeSpans": [{
        "spans": [{
          "traceId": "abc123",
          "spanId": "span456",
          "name": "chat gpt-4o",
          "startTimeUnixNano": "1710000000000000000",
          "endTimeUnixNano": "1710000001000000000",
          "attributes": [
            {"key": "gen_ai.operation.name", "value": {"stringValue": "chat"}},
            {"key": "gen_ai.request.model", "value": {"stringValue": "gpt-4o"}},
            {"key": "gen_ai.provider.name", "value": {"stringValue": "openai"}},
            {"key": "gen_ai.usage.input_tokens", "value": {"intValue": 150}},
            {"key": "gen_ai.usage.output_tokens", "value": {"intValue": 50}}
          ]
        }]
      }]
    }]
  }'

REST API端点

框架集成

开发包

对于不支持原生OTel的框架，请使用Argus SDK：

from argus.sdk.reporter import ArgusReporter

reporter = ArgusReporter(
    endpoint="http://localhost:8000",
    agent_name="my-agent",
    api_key="your-api-key",  # optional
)

await reporter.report_span(
    operation="chat",
    model="gpt-4o",
    input_tokens=150,
    output_tokens=50,
    latency_ms=1200,
)

建筑

Agent Frameworks (LangGraph, CrewAI, OpenAI, ...)
         |
         | OTLP/REST
         v
  Ingestion Layer (/v1/traces)
         |
         v
  Argus Core (FastAPI)
  +-- Metrics Engine (windowed aggregation)
  +-- Cost Calculator (config-driven pricing)
  +-- Alert Engine (rule evaluation + webhooks)
  +-- Config Manager (hot-reload via watchdog)
  +-- SSE Broadcaster (real-time updates)
         |
         | HTML partials via SSE
         v
  Frontend (HTMX + Alpine.js + Tailwind)

技术栈

数据库迁移

Argus使用Alembic进行数据库模式迁移，同时支持SQLite和PostgreSQL：

# Run migrations
alembic upgrade head

# Create a new migration after model changes
alembic revision --autogenerate -m "description"

# Use PostgreSQL
DATABASE_URL="postgresql+asyncpg://user:pass@localhost/argus" alembic upgrade head

测试

# Run all tests
pytest

# Run with coverage report
pytest --cov=src/argus --cov-report=term-missing

# Run a specific test file
pytest tests/unit/test_security.py -v

# Lint and type check
ruff check src/ tests/
ruff format --check src/ tests/
mypy src/argus/

项目结构

argus-panoptes/
+-- config/              # YAML configuration (hot-reloaded)
+-- src/argus/
|   +-- core/            # Config, database, SSE, security
|   +-- models/          # SQLModel data models
|   +-- routes/api/      # REST API endpoints
|   +-- routes/views/    # HTMX view routes
|   +-- services/        # Business logic
|   +-- schemas/         # Pydantic request/response schemas
|   +-- sdk/             # Python SDK for non-OTel frameworks
+-- tests/               # pytest test suite
+-- migrations/          # Alembic database migrations
+-- docker/              # Dockerfiles and compose
+-- static/              # CSS, JS assets
+-- .github/workflows/   # CI/CD pipelines

贡献

看 贡献.md 用于开发设置、代码风格、测试和PR过程。

安全

看 安全.md 漏洞报告指南。

许可证

Apache许可证2.0。看 许可证 全文。