百眼巨人
您的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:8000Docker（生产）
# 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端点
| 方法 | 路径 | 描述 |
|---|---|---|
GET | /health | 健康检查 |
POST | /v1/traces | 摄入OTLP跟踪数据 |
GET | /api/v1/agents | 列出注册代理人 |
GET | /api/v1/agents/{id} | 获取代理详细信息 |
GET | /api/v1/agents/{id}/metrics | 获取代理指标 |
GET | /api/v1/traces | 搜索痕迹 |
GET | /api/v1/traces/{id} | 获取跟踪详细信息 |
GET | /api/v1/metrics/summary | 获取指标摘要 |
GET | /api/v1/alerts | 列出警报规则 |
GET | /api/v1/config | 获取当前配置 |
PUT | /api/v1/config | 更新配置 |
框架集成
| 框架 | 集成方法 |
|---|---|
| LangGraph/LangChain | OTel采集器--集 OTEL_EXPORTER_OTLP_ENDPOINT |
| CrewAI | 原生OTel仪器 |
| OpenAI代理SDK | OTel Python SDK包装器或Argus SDK垫片 |
| 谷歌ADK | OTel收集器 |
| PydanticAI | 原生OTel支持 |
| AutoGen | opentelemetry-instrumentation-autogen |
| 语义内核 | 微软OTel集成 |
| 自定义代理 | REST API或Argus Python SDK |
开发包
对于不支持原生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)技术栈
| 层 | 技术 |
|---|---|
| 后端 | Python 3.12+、FastAPI、SQLModel、SQLAlchemy异步 |
| 前端 | HTMX 2.x，Alpine.js 3.x，顺风CSS 4.x |
| 数据库 | SQLite（开发）/PostgreSQL（产品） |
| 实时 | 服务器发送事件（SSE） |
| 配置 | 带看门狗热重载的YAML |
| 容器 | Docker多级，非root |
数据库迁移
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。看 许可证 全文。