Maxim 集成

Maxim 概览

Maxim AI 为你的 CrewAI 应用提供全面的代理监控、评估和可观测性。借助 Maxim 的一行集成，你可以轻松追踪代理交互、性能指标等内容。

功能

提示管理

Maxim 的提示管理能力使你能够为 CrewAI 代理创建、组织和优化提示词。你不必将指令硬编码，而是可以利用 Maxim 的 SDK 动态获取并应用受版本控制的提示词。

Prompt Playground

通过 playground 创建、优化、试验并部署提示词。你可以使用文件夹和版本来组织提示词，通过把工具和上下文连接到真实场景中进行实验，并基于自定义逻辑完成部署。

通过配置模型并在提示 playground 顶部的下拉菜单中选择对应模型，可以轻松在不同模型之间试验。

Prompt Versions

当团队构建 AI 应用时，实验的重要一部分就是不断迭代提示结构。为了高效协作并清晰组织变更，Maxim 支持提示版本管理以及跨版本对比运行。

Prompt Comparisons

随着 AI 应用的发展，你需要在不同模型、不同提示结构等维度进行实验。为了比较版本并就变更做出明智决策，对比 playground 提供并排查看结果的方式。

为什么使用 Prompt comparison？

Prompt comparison 会将多个单独的 Prompt 合并到一个视图中，为多种工作流提供更流畅的方式：

1. 模型比较：评估同一 Prompt 在不同模型上的表现。
2. 提示优化：比较不同版本的 Prompt，找出最有效的表达方式。
3. 跨模型一致性：确保同一 Prompt 在不同模型上的输出一致。
4. 性能基准测试：分析不同模型和 Prompt 之间的延迟、成本和 token 数量等指标。

可观测性与评估

Maxim AI 为你的 CrewAI 代理提供全面的可观测性和评估，帮助你准确了解每次执行中发生了什么。

Agent Tracing

轻松跟踪代理的完整生命周期，包括工具调用、代理轨迹和决策流。

Analytics + Evals

对完整 trace 或单个节点运行详细评估，支持：

• 多步交互和细粒度 trace 分析
• 会话级评估
• 真实场景测试模拟

Auto Evals on Logs

根据过滤条件和采样规则，从 UI 自动评估已捕获的日志。

Human Evals on Logs

使用人工评估或评分来检查日志质量并进行评价。

Node Level Evals

评估 trace 或日志中的任意组件，从而更深入理解代理行为。

---

Alerting

为错误、成本、token 使用量、用户反馈和延迟设置阈值，并通过 Slack 或 PagerDuty 接收实时告警。

Dashboards

轻松可视化随时间变化的 traces、使用指标、延迟和错误率。

开始使用

前置条件

• Python 版本 >=3.10
• 一个 Maxim 账户（点此注册）
• 生成 Maxim API Key
• 一个 CrewAI 项目

安装

通过 pip 安装 Maxim SDK：

pip install maxim-py

或者将其加入你的 requirements.txt：

maxim-py

基础设置

1. 配置环境变量

### Environment Variables Setup

# Create a `.env` file in your project root:

# Maxim API Configuration
MAXIM_API_KEY=your_api_key_here
MAXIM_LOG_REPO_ID=your_repo_id_here

2. 导入所需包

from crewai import Agent, Task, Crew, Process
from maxim import Maxim
from maxim.logger.crewai import instrument_crewai

3. 使用你的 API key 初始化 Maxim

# Instrument CrewAI with just one line
instrument_crewai(Maxim().logger())

4. 像平常一样创建并运行你的 CrewAI 应用

# Create your agent
researcher = Agent(
    role='Senior Research Analyst',
    goal='Uncover cutting-edge developments in AI',
    backstory="You are an expert researcher at a tech think tank...",
    verbose=True,
    llm=llm
)

# Define the task
research_task = Task(
    description="Research the latest AI advancements...",
    expected_output="",
    agent=researcher
)

# Configure and run the crew
crew = Crew(
    agents=[researcher],
    tasks=[research_task],
    verbose=True
)

try:
    result = crew.kickoff()
finally:
    maxim.cleanup()  # Ensure cleanup happens even if errors occur

就是这样！现在你所有的 CrewAI 代理交互都会被记录，并可在 Maxim 仪表盘中查看。

查看这个 Google Colab Notebook 获取快速参考 - Notebook

查看你的追踪

运行 CrewAI 应用后：

1. 登录你的 Maxim Dashboard

2. 进入你的 repository

3. 查看详细的代理追踪，包括：

   • 代理对话
   • 工具使用模式
   • 性能指标
   • 成本分析
   

故障排查

常见问题

• 没有出现 traces：确保你的 API key 和 repository ID 正确

• 确保在运行 crew 之前**调用了 instrument_crewai()**。这样才能正确初始化日志钩子。

• 在 instrument_crewai() 调用中设置 debug=True，以暴露任何内部错误：

  instrument_crewai(logger, debug=True)

• 配置代理时使用 verbose=True 以捕获详细日志：

  agent = CrewAgent(..., verbose=True)

• 再次确认 instrument_crewai() 是在创建或执行代理之前调用的。这可能显而易见，但确实是个常见疏漏。

资源

CrewAI 文档

官方 CrewAI 文档

Maxim 文档

官方 Maxim 文档

Maxim Github

Maxim Github