---
title: Instructor
description: Learn how to implement and monitor Instructor traces with Agenta for enhanced LLM observability. This comprehensive guide covers setup, configuration, and best practices for tracking structured data extraction using Instructor and OpenAI models.
---

```mdx-code-block
import Image from "@theme/IdealImage";
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';
```

[Instructor](https://python.useinstructor.com/) is a library that helps you extract structured data from natural language using LLMs. By instrumenting Instructor with Agenta, you can monitor and debug your applications more effectively.

This guide shows you how to instrument Instructor when using OpenAI models, you can use the same approach for other LLM providers like Anthropic, Google, etc. You just need to use the correct instrumentation library for the LLM provider.

<Image
  style={{ display: "block", margin: "10 auto" }}
  img={require("/images/observability/instructor.png")}
  alt="Illustration of instructor instrumented trace"
  loading="lazy"
/>

## Installation

Install the required packages:

```bash
pip install -U agenta openai opentelemetry-instrumentation-openai instructor
```

## Configure Environment Variables

<Tabs>
<TabItem value="cloud" label="Agenta Cloud or Enterprise">

```python
import os

os.environ["AGENTA_API_KEY"] = "YOUR_AGENTA_API_KEY"
os.environ["AGENTA_HOST"] = "https://cloud.agenta.ai"
```

</TabItem>
<TabItem value="oss" label="Agenta OSS Running Locally">

```python
import os

os.environ["AGENTA_HOST"] = "http://localhost"
```

</TabItem>
</Tabs>

## Code Example

```python
# highlight-next-line
import agenta as ag
import openai
import instructor
from pydantic import BaseModel
# highlight-next-line
from opentelemetry.instrumentation.openai import OpenAIInstrumentor

# highlight-next-line
ag.init()

# highlight-start
# Instrument OpenAI before creating the Instructor client
OpenAIInstrumentor().instrument()
# highlight-end

class UserInfo(BaseModel):
    name: str
    age: int

# highlight-next-line
@ag.instrument(spankind="WORKFLOW")
def instructor_workflow():
    # Create an Instructor client using the instrumented OpenAI model
    client = instructor.from_openai(openai.OpenAI())

    # Extract structured data from natural language
    user_info = client.chat.completions.create(
        model="gpt-3.5-turbo",
        response_model=UserInfo,
        messages=[{"role": "user", "content": "John Doe is 30 years old."}],
    )
    return user_info

user_info = instructor_workflow()
print(user_info)
```

:::warning
**Order Matters**: Call `OpenAIInstrumentor().instrument()` **before** creating the Instructor client with `instructor.from_openai(openai.OpenAI())`. Both modify the OpenAI library, so the order ensures proper instrumentation.
:::

## Explanation

- **Initialize Agenta**: `ag.init()` sets up the Agenta SDK.
- **Instrument OpenAI**: `OpenAIInstrumentor().instrument()` instruments the OpenAI library for tracing. This must come **before** creating the Instructor client.
- **Instrument the Workflow**: The `@ag.instrument(spankind="WORKFLOW")` decorator creates a parent span. This is optional, but it's a good practice to instrument the main function of your application.
