CrewAI 연구 크루를 위한 AgentOps 관측성

# AgentOps Observability for CrewAI Agent

Below is the minimal diff to add AgentOps tracing to your CrewAI + LlamaIndex agent. I'm assuming a typical layout (`main.py` entrypoint, `crew.py` for the crew, `retriever.py` for the LlamaIndex query engine). Adjust paths to match your repo.

## Diff

```diff
diff --git a/.env.example b/.env.example
index 1111111..2222222 100644
--- a/.env.example
+++ b/.env.example
@@ -1,5 +1,6 @@
 OPENAI_API_KEY=sk-...
+AGENTOPS_API_KEY=your-agentops-key
 # optional
 LLAMA_INDEX_VERSION=v1
```

```diff
diff --git a/requirements.txt b/requirements.txt
index 3333333..4444444 100644
--- a/requirements.txt
+++ b/requirements.txt
@@ -1,4 +1,5 @@
 crewai
 llama-index
 python-dotenv
+agentops
```

```diff
diff --git a/main.py b/main.py
index 5555555..6666666 100644
--- a/main.py
+++ b/main.py
@@ -1,20 +1,45 @@
+import os
+import uuid
+
+import agentops
 from dotenv import load_dotenv
 
 from crew import build_crew
 from retriever import get_query_engine
 
 load_dotenv()
 
+
 def main() -> None:
-    crew = build_crew()
-    result = crew.kickoff()
-    print(result)
+    run_id = str(uuid.uuid4())
+    index_version = os.environ.get("LLAMA_INDEX_VERSION", "v1")
+
+    agentops.init(
+        api_key=os.environ["AGENTOPS_API_KEY"],
+        tags=["crewai", "llamaindex"],
+    )
+    try:
+        agentops.set_session_metadata(
+            crew_name="research_crew",
+            run_id=run_id,
+            retriever_index_version=index_version,
+        )
+
+        crew = build_crew()
+        result = crew.kickoff()
+        print(result)
+
+        # (5) per-session evaluation score from existing output check
+        score = 1.0 if output_check_passes(result) else 0.0
+        agentops.record_evaluation(
+            name="output_check",
+            score=score,
+            metadata={"run_id": run_id},
+        )
+    finally:
+        agentops.end_session("Success")
 
 
 if __name__ == "__main__":
     main()
```

```diff
diff --git a/retriever.py b/retriever.py
index 7777777..8888888 100644
--- a/retriever.py
+++ b/retriever.py
@@ -1,10 +1,22 @@
+import agentops
 from llama_index.core import VectorStoreIndex
 
 
 def get_query_engine(index: VectorStoreIndex):
     return index.as_query_engine()
 
 
 def query(engine, question: str):
-    return engine.query(question)
+    with agentops.start_span("llamaindex_query") as span:
+        response = engine.query(question)
+        nodes = getattr(response, "source_nodes", []) or []
+        span.set_attribute("node_count", len(nodes))
+        span.set_attribute("question_length", len(question))
+        return response
```

## Notes on each step

1. **Install + env**: `pip install agentops`, add `AGENTOPS_API_KEY` to `.env.example`, read via `os.environ["AGENTOPS_API_KEY"]` (fails fast if missing).
2. **Init once at entrypoint**: `agentops.init()` is called in `main()` before `build_crew()`. `end_session` is in a `finally` so it runs even on exceptions. If you have multiple entrypoints, move init into a shared `bootstrap.py` and call it from each.
3. **Session metadata**: `set_session_metadata` tags the session with `crew_name`, `run_id`, and `retriever_index_version`. These show up as filterable attributes in the dashboard.
4. **Retrieval span**: `agentops.start_span("llamaindex_query")` wraps the query engine call. `node_count` is derived from `response.source_nodes` (LlamaIndex's standard field). Latency is captured automatically by the span's start/end timestamps.
5. **Evaluation score**: `record_evaluation` records a per-session score from your existing `output_check_passes` helper. If your check returns a float already, pass it directly.

## Verifying traces in the dashboard

1. **Run the agent locally** with a valid key:
   ```bash
   export AGENTOPS_API_KEY=...
   python main.py
   ```
   You should see an AgentOps session URL printed in the console (e.g. `https://app.agentops.ai/sessions/<id>`).

2. **Open the session** in the AgentOps dashboard. Confirm:
   - **Session metadata** shows `crew_name`, `run_id`, `retriever_index_version`.
   - **Spans** include `llamaindex_query` with `node_count` and a latency value.
   - **Evaluations** tab shows `output_check` with the score.
   - **CrewAI events** (agent steps, tool calls) appear as child spans under the session.

3. **Sanity checks if traces are missing**:
   - `agentops.init()` must run before any CrewAI/LlamaIndex object is constructed — otherwise auto-instrumentation won't attach.
   - Confirm `agentops` version supports your CrewAI version (`pip show agentops crewai`); CrewAI instrumentation is version-sensitive.
   - Check the console for `AgentOps: Session started` / `Session ended` log lines.
   - If `end_session` is never called (e.g. process killed), the session may appear as "in progress" — the `finally` block prevents this for normal exits.

4. **CI verification** (optional): assert the session URL is printed and exit code is 0; the dashboard is the source of truth for span content.