AgentEye 入门指南

本指南将带您完成 AgentEye 的全套配置：部署服务器与控制台、在 Agent 机器上安装采集器，以及在 Python Agent 代码中接入埋点。

AgentEye 是什么？

AgentEye 是一个自托管的 AI Agent 可观测性与评估平台。它会记录 Agent 的每一个动作——运行过程中的每一步——并自动对每次已完成的运行进行质量评分，让您清晰掌握 Agent 在生产环境中的行为表现，在用户发现问题之前率先捕获回归。数据单向流转：您的 Agent 代码通过 Python SDK 发出事件 → 轻量级采集器守护进程批量上报至服务器 → 事件与分析数据存储于 ClickHouse（组织、用户、API 密钥、控制台、保存的查询等操作状态存储于 Postgres）→ 您在控制台中查阅一切。您将获得：

事件 —— 每次 Agent 运行的原始逐步记录（工具调用、模型调用、钩子、错误）。
会话 —— 将事件汇总为每次运行一行，每行均自动评估并打分。
评估 —— 由您自己的评估服务产出的质量评分，无需人工审查即可发现质量下降。
查询与控制台 —— 基于您的数据保存 ClickHouse SQL 查询，并以图表形式呈现在组织级共享控制台中。
告警与事故 —— 阈值规则触发通知（邮件、Slack、Webhook、控制台内），并配有事故处理工作流。
CLI 与 AI 助手 —— 终端客户端（agenteye）以及控制台内置助手，支持用自然语言提问。

所有组件均运行在您自己的基础设施中，可以是单个 Docker Compose 栈（本指南）、生产级 Kubernetes 部署，或单一的同置 Pod。本指南将端到端地完成 Compose 栈的搭建。

第一步：身份认证

所有 AgentEye 制品均从 agenteye-enterprise GitHub 组织分发。作为企业开发者，您可以生成自己的 GitHub PAT。请按照 enterprise-docs/github-token.md 中的步骤和所需权限进行操作。

export AGENTEYE_TOKEN=<your-github-pat>

# 向 GHCR 进行 Docker 身份认证
echo $AGENTEYE_TOKEN | docker login ghcr.io -u x --password-stdin

第二步：部署服务器与控制台

服务器负责接收来自采集器的事件并使其可查询；控制台是您探索数据的地方。采集的事件与分析数据存储于 ClickHouse（必需的分析存储），而 Postgres 保存组织、用户、API 密钥、控制台和已保存查询等操作状态。 下载已发布的 Compose 文件：

mkdir -p ./agenteye
curl -fsSL \
  -H "Authorization: token $AGENTEYE_TOKEN" \
  https://raw.githubusercontent.com/agenteye-enterprise/releases/main/docker-compose.yml \
  -o ./agenteye/docker-compose.yml
cd agenteye

配置密钥： 创建一个 .env 文件，避免使用默认的 admin 凭据运行。至少需要设置 ADMIN_KEY 和 POSTGRES_PASSWORD：

POSTGRES_PASSWORD=your-db-password
ADMIN_KEY=your-admin-secret

启动服务栈：

docker compose up -d

这将启动完整的服务栈，包括必需的 ClickHouse 分析存储、可选的 Redis 缓存，以及服务器和控制台。服务器启动前 ClickHouse 必须处于健康状态。服务器现在监听 http://localhost:8080，控制台监听 http://localhost:3000。如需生产部署（自定义 Postgres、TLS、反向代理），请参阅 enterprise-docs/deployment.md。

第三步：为采集器创建 API 密钥

每个采集器使用一个具有特定权限的 API 密钥进行身份认证。使用第二步中设置的 ADMIN_KEY 来创建：

curl -s -X POST http://localhost:8080/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"prod-collector","key":"your-collector-secret","permissions":["events:add"]}'

key 的值由您自行提供，在第四步的采集器配置中使用它。完整的密钥管理请参阅 enterprise-docs/api-keys.md。

第四步：安装采集器

在每台运行 AI Agent 的机器上安装采集器守护进程。 下载二进制文件（Linux x86_64）：

VERSION=0.0.1-beta.13
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "collector/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-collector-linux-x86_64'
chmod +x agenteye-collector-linux-x86_64
sudo mv agenteye-collector-linux-x86_64 /usr/local/bin/agenteye-collector

此命令下载的是 Linux x86_64 构建版本。如需 macOS（Apple Silicon 或 Intel）、Linux arm64，或 Docker / systemd / launchd 安装方式，请参阅 collector-installation.md，其中列出了各平台的下载方式——上述命令安装的是 Linux 二进制文件，无法在其他平台运行。

配置：

mkdir -p ~/.agenteye
cat > ~/.agenteye/config.json <<EOF
{
  "url": "http://your-server-host:8080/events",
  "key": "the-key-from-step-3"
}
EOF

启动守护进程：

agenteye-collector start

使用单次刷新验证连通性（刷新完所有待处理事件后退出）：

agenteye-collector flush

Docker、systemd 和 launchd 的安装方式请参阅 enterprise-docs/collector-installation.md。

第五步：安装 Python SDK

在每台需要对 Agent 代码进行埋点的机器上，从 GitHub Releases 安装 wheel 包。

VERSION=0.0.1b9
GITHUB_TOKEN=$AGENTEYE_TOKEN gh release download "python-sdk/v${VERSION}" \
  --repo agenteye-enterprise/releases \
  --pattern 'agenteye-*.whl'
pip install agenteye-${VERSION}-py3-none-any.whl

第六步：为您的 Agent 添加埋点

在 Agent 代码中添加事件。至少需要发出 agent_start 和 agent_end：

import agenteye

agenteye.event.agent_start(
    session_id="run-001",
    agent_id="my-agent",
    goal="answer the user query",
)

# 您的 Agent 逻辑

agenteye.event.agent_end(
    session_id="run-001",
    agent_id="my-agent",
    outcome="success",
)

事件会被缓冲，并每 500 毫秒刷新到 $AGENTEYE_HOME/events/（如果未设置 AGENTEYE_HOME，则写入 ~/.agenteye/events/）。采集器会自动采集这些事件。完整的事件 API 请参阅 enterprise-docs/python-sdk.md。