From b0d89698fdd3eb5aced8e659f2241f0648b8a40b Mon Sep 17 00:00:00 2001
From: Akshit Madan <56507451+akmadan@users.noreply.github.com>
Date: Sun, 8 Jun 2025 23:09:01 +0530
Subject: [PATCH] docs: added Maxim support for Agent Observability (#2861)

* docs: added Maxim support for Agent Observability

* enhanced the maxim integration doc page as per the github PR reviewer bot suggestions

* Update maxim-observability.mdx

* Update maxim-observability.mdx

- Fixed Python version, >=3.10
- added expected_output field in Task
- Removed marketing links and added github link

* added maxim in observability

---------

Co-authored-by: Tony Kipkemboi <iamtonykipkemboi@gmail.com>
---
 docs/docs.json               |   1 +
 docs/observability/maxim.mdx | 152 +++++++++++++++++++++++++++++++++++
 2 files changed, 153 insertions(+)
 create mode 100644 docs/observability/maxim.mdx

diff --git a/docs/docs.json b/docs/docs.json
index 12ae81cd1..676d9a168 100644
--- a/docs/docs.json
+++ b/docs/docs.json
@@ -201,6 +201,7 @@
               "observability/arize-phoenix",
               "observability/langfuse",
               "observability/langtrace",
+              "observability/maxim",
               "observability/mlflow",
               "observability/openlit",
               "observability/opik",
diff --git a/docs/observability/maxim.mdx b/docs/observability/maxim.mdx
new file mode 100644
index 000000000..0e03e1242
--- /dev/null
+++ b/docs/observability/maxim.mdx
@@ -0,0 +1,152 @@
+---
+title: Maxim Integration
+description: Start Agent monitoring, evaluation, and observability
+icon: bars-staggered
+---
+
+# Maxim Integration
+
+Maxim AI provides comprehensive agent monitoring, evaluation, and observability for your CrewAI applications. With Maxim's one-line integration, you can easily trace and analyse agent interactions, performance metrics, and more.
+
+
+## Features: One Line Integration
+
+- **End-to-End Agent Tracing**: Monitor the complete lifecycle of your agents
+- **Performance Analytics**: Track latency, tokens consumed, and costs
+- **Hyperparameter Monitoring**: View the configuration details of your agent runs
+- **Tool Call Tracking**: Observe when and how agents use their tools
+- **Advanced Visualisation**: Understand agent trajectories through intuitive dashboards
+
+## Getting Started
+
+### Prerequisites
+
+- Python version >=3.10
+- A Maxim account ([sign up here](https://getmaxim.ai/))
+- A CrewAI project
+
+### Installation
+
+Install the Maxim SDK via pip:
+
+```python
+pip install maxim-py>=3.6.2
+```
+
+Or add it to your `requirements.txt`:
+
+```
+maxim-py>=3.6.2
+```
+
+
+### Basic Setup
+
+### 1. Set up environment variables
+
+```python
+### 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. Import the required packages
+
+```python
+from crewai import Agent, Task, Crew, Process
+from maxim import Maxim
+from maxim.logger.crewai import instrument_crewai
+```
+
+### 3. Initialise Maxim with your API key
+
+```python
+# Initialize Maxim logger
+logger = Maxim().logger()
+
+# Instrument CrewAI with just one line
+instrument_crewai(logger)
+```
+
+### 4. Create and run your CrewAI application as usual
+
+```python
+
+# 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
+```
+
+That's it! All your CrewAI agent interactions will now be logged and available in your Maxim dashboard.
+
+Check this Google Colab Notebook for a quick reference - [Notebook](https://colab.research.google.com/drive/1ZKIZWsmgQQ46n8TH9zLsT1negKkJA6K8?usp=sharing)
+
+## Viewing Your Traces
+
+After running your CrewAI application:
+
+![Example trace in Maxim showing agent interactions](https://raw.githubusercontent.com/maximhq/maxim-docs/master/images/Screenshot2025-05-14at12.10.58PM.png)
+
+1. Log in to your [Maxim Dashboard](https://getmaxim.ai/dashboard)
+2. Navigate to your repository
+3. View detailed agent traces, including:
+    - Agent conversations
+    - Tool usage patterns
+    - Performance metrics
+    - Cost analytics
+
+## Troubleshooting
+
+### Common Issues
+
+- **No traces appearing**: Ensure your API key and repository ID are correc
+- Ensure you've **called `instrument_crewai()`** ***before*** running your crew. This initializes logging hooks correctly.
+- Set `debug=True` in your `instrument_crewai()` call to surface any internal errors:
+    
+    ```python
+    instrument_crewai(logger, debug=True)
+    ```
+    
+- Configure your agents with `verbose=True` to capture detailed logs:
+    
+    ```python
+    
+    agent = CrewAgent(..., verbose=True)
+    ```
+    
+- Double-check that `instrument_crewai()` is called **before** creating or executing agents. This might be obvious, but it's a common oversight.
+
+### Support
+
+If you encounter any issues:
+
+- Check the [Maxim Documentation](https://getmaxim.ai/docs)
+- Maxim Github [Link](https://github.com/maximhq)