HoneyHive

https://docs.honeyhive.ai/v2/
Admin
HoneyHive provides a comprehensive platform with API, CLI, and SDK references, along with guides for...
Tokens:282,999
Snippets:2,589
Trust Score:8
Update:4 months ago
Show doc for...
Tokens:
Raw
### Example: Multi-Agent Routing Setup

Source: https://docs.honeyhive.ai/v2/integrations/langchain

Sets up the foundational components for a multi-agent routing example in LangChain with HoneyHive tracing enabled. Includes tool definitions and tracer initialization.

```python
import os
from honeyhive import HoneyHiveTracer, trace
from openinference.instrumentation.langchain import LangChainInstrumentor
from langchain.agents import create_agent
from langchain_core.tools import tool

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
LangChainInstrumentor().instrument(tracer_provider=tracer.provider)

@tool
def calculator(expression: str) -> str:
    """Evaluate arithmetic."""
    return str(eval(expression, {"__builtins__": {}}, {}))

@tool
def policy_lookup(topic: str) -> str:
    """Look up company policy."""
    policies = {"soc2": "SOC 2 covers security and privacy controls.", "retention": "30-day default."}
    return policies.get(topic.lower(), "No policy found.")

```

--------------------------------

### Example: Single Agent with Tools

Source: https://docs.honeyhive.ai/v2/integrations/openai-agents

Demonstrates setting up a single agent with multiple tools (lookup_order_status, lookup_policy) and running it with a complex user query. The setup includes HoneyHive initialization and instrumentation.

```python
import asyncio
import os

from agents import Agent, Runner, function_tool
from openinference.instrumentation.openai_agents import OpenAIAgentsInstrumentor

from honeyhive import HoneyHiveTracer

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
OpenAIAgentsInstrumentor().instrument(tracer_provider=tracer.provider)


@function_tool
def lookup_order_status(order_id: str) -> str:
    """Look up the current status and ETA for a customer order."""
    statuses = {
        "ORD-1001": {"state": "shipped", "eta_days": 2},
        "ORD-1002": {"state": "processing", "eta_days": 5},
        "ORD-1003": {"state": "delayed", "eta_days": 8},
    }
    status = statuses.get(order_id.upper())
    if status:
        return (
            f"Order {order_id.upper()}: {status['state']}, "
            f"estimated delivery in {status['eta_days']} days."
        )
    return f"Order {order_id.upper()}: not found in the system."


@function_tool
def lookup_policy(topic: str) -> str:
    """Look up support policy by topic: refund, cancellation, or shipping."""
    policies = {
        "refund": "Refunds are available within 30 days for undelivered or damaged items.",
        "cancellation": "Cancellation is allowed before shipment. Delayed orders can request assisted cancellation.",
        "shipping": "Delays beyond 7 days trigger proactive support outreach.",
    }
    return policies.get(topic.strip().lower(), "No policy found.")


agent = Agent(
    name="Support Generalist",
    instructions=(
        "You are a customer support generalist. Use tools for order status and "
        "policy questions, then reply with short, customer-friendly answers."
    ),
    tools=[lookup_order_status, lookup_policy],
)


async def main():
    await Runner.run(
        agent,
        "For delayed order ORD-1003, explain the cancellation policy and "
        "recommended next steps.",
    )
    tracer.force_flush()


asyncio.run(main())
```

--------------------------------

### Quick start: Create a session and log an OpenAI call

Source: https://docs.honeyhive.ai/v2/sdk-reference/typescript

This example demonstrates how to create a new session, log a model event for an OpenAI call, execute the OpenAI call, and then update the event with the response details and duration.

```APIDOC
## Quick start: Create a session and log an OpenAI call

### Description
This example demonstrates how to create a new session, log a model event for an OpenAI call, execute the OpenAI call, and then update the event with the response details and duration.

### Method
POST, PUT

### Endpoint
/sessions, /events

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
##### client.sessions.create
- **session_name** (string) - Required - The name of the session.
- **source** (string) - Required - The source of the session.

##### client.events.create
- **session_id** (string) - Required - The ID of the session to which the event belongs.
- **event_type** (string) - Required - The type of the event (e.g., 'model').
- **event_name** (string) - Required - The name of the event (e.g., 'chat-completion').
- **config** (object) - Required - Configuration for the event, including the model used.
  - **model** (string) - Required - The model used for the event.
- **inputs** (object) - Required - The inputs provided to the model.
  - **messages** (array) - Required - An array of message objects for the chat completion.
    - **role** (string) - Required - The role of the message sender (e.g., 'user').
    - **content** (string) - Required - The content of the message.

##### client.events.update
- **event_id** (string) - Required - The ID of the event to update.
- **outputs** (object) - Optional - The outputs from the model.
  - **content** (string) - Required - The content of the model's response.
- **duration** (number) - Optional - The duration of the model call in milliseconds.
- **metadata** (object) - Optional - Additional metadata about the model call.
  - **model** (string) - Required - The model used for the call.
  - **usage** (object) - Required - Usage statistics for the model call.

### Request Example
```typescript
import { Client } from '@honeyhive/api-client';
import OpenAI from 'openai';

const client = new Client();
const openai = new OpenAI();

// 1. Start a session (trace)
const session = await client.sessions.create({
  session_name: 'openai-example',
  source: 'dev',
});

// 2. Create a model event for the OpenAI call
const startTime = Date.now();
const event = await client.events.create({
  session_id: session.session_id,
  event_type: 'model',
  event_name: 'chat-completion',
  config: { model: 'gpt-4o-mini' },
  inputs: {
    messages: [{ role: 'user', content: 'What is the meaning of life?' }],
  },
});

// 3. Make the OpenAI call
const completion = await openai.chat.completions.create({
  model: 'gpt-4o-mini',
  messages: [{ role: 'user', content: 'What is the meaning of life?' }],
});
const { content } = completion.choices[0].message;
console.log(content);

// 4. Update the event with the response
if (content) {
  await client.events.update({
    event_id: event.event_id,
    outputs: { content },
    duration: Date.now() - startTime,
    metadata: {
      model: completion.model,
      usage: completion.usage,
    },
  });
}
```

### Response
#### Success Response (200)
- **session_id** (string) - The ID of the created session.
- **event_id** (string) - The ID of the created event.

#### Response Example
```json
{
  "session_id": "sess_abc123",
  "event_id": "evt_xyz789"
}
```
```

--------------------------------

### Logger SDK Example

Source: https://docs.honeyhive.ai/v2/sdk-reference/python/migration/logger-to-v1

Example of how to use the older honeyhive-logger to start a session, log an event, and update it with metrics and outputs.

```python
from honeyhive_logger import start, log, update

def handle_chat(message: str, user_id: str) -> str:
    session_id = start(
        session_name="support-chat",
        inputs={"message": message},
        user_properties={"user_id": user_id},
    )

    response = call_model(message)
    event_id = log(
        session_id=session_id,
        event_name="model_inference",
        event_type="model",
        inputs={"prompt": message},
        outputs={"response": response},
    )

    update(event_id=event_id, metrics={"quality_score": score(response)})
    update(event_id=session_id, outputs={"response": response})
    return response
```

--------------------------------

### Start Session with Old Logger

Source: https://docs.honeyhive.ai/v2/sdk-reference/typescript-logger-to-api-sdk-migration

Example of initiating a session using the previous TypeScript logger's `start` function. Note the parameter structure.

```typescript
const sessionId = await start({
  apiKey: "hh_...",
  project: "my-project",
  sessionName: "my-session",
  source: "dev",
  config: {
    /* ... */
  },
  inputs: {
    /* ... */
  },
  metadata: {
    /* ... */
  },
  userProperties: {
    /* ... */
  },
});
```

--------------------------------

### Start the Agent Server

Source: https://docs.honeyhive.ai/v2/tutorials/distributed-tracing

Run this command in your terminal to start the agent server. Ensure it is started before the client application.

```bash
python agent_server.py
```

--------------------------------

### Install LiteLLM with HoneyHive

Source: https://docs.honeyhive.ai/v2/integrations/litellm

Install the necessary packages for HoneyHive observability with LiteLLM. You can install them together or separately.

```bash
pip install "honeyhive[openinference-litellm]"

# Or install separately
pip install honeyhive openinference-instrumentation-litellm litellm
```

--------------------------------

### Example: Multi-Agent Delegation

Source: https://docs.honeyhive.ai/v2/integrations/pydantic-ai

Illustrates a multi-agent setup where a coordinator agent delegates policy questions to a specialist agent. HoneyHive traces the full hierarchy of agent interactions and tool executions.

```python
import asyncio
import os
from dataclasses import dataclass

from pydantic_ai import Agent, RunContext

from honeyhive import HoneyHiveTracer

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
Agent.instrument_all()


@dataclass
class CustomerContext:
    customer_name: str
    order_id: str


policy_agent = Agent(
    "anthropic:claude-haiku-4-5",
    name="policy_specialist",
    instructions=(
        "You are a policy specialist. Give concise answers about "
        "refund, cancellation, and shipping policies."
    ),
)

coordinator = Agent(
    "anthropic:claude-haiku-4-5",
    name="support_coordinator",
    deps_type=CustomerContext,
    instructions=(
        "You are a support coordinator. For policy questions, "
        "delegate to ask_policy_specialist. Combine the answer "
        "with any order context to form your response. Be concise."
    ),
)


@coordinator.tool
async def ask_policy_specialist(
    ctx: RunContext[CustomerContext], question: str
) -> str:
    """Delegate policy questions to the specialist."""
    result = await policy_agent.run(question, usage=ctx.usage)
    return str(result.output)


async def main():
    customer = CustomerContext(customer_name="Jordan Lee", order_id="ORD-1003")
    await coordinator.run(
        "Order ORD-1003 is delayed. Can I cancel and get a refund?",
        deps=customer,
    )


asyncio.run(main())
```

--------------------------------

### Run Cursor SDK Example

Source: https://docs.honeyhive.ai/v2/integrations/cursor-sdk

Execute the example script to initiate a traced Cursor SDK run.

```bash
pnpm start
```

--------------------------------

### Install the HoneyHive API Client

Source: https://docs.honeyhive.ai/v2/sdk-reference/typescript

Install the @honeyhive/api-client package using npm.

```sh
npm install @honeyhive/api-client
```

--------------------------------

### Install Full HoneyHive Package

Source: https://docs.honeyhive.ai/v2/introduction/troubleshooting

Install the complete HoneyHive package including all integrations.

```bash
pip install "honeyhive[all]"
```

--------------------------------

### Install HoneyHive and Pydantic AI

Source: https://docs.honeyhive.ai/v2/integrations/pydantic-ai

Install the necessary libraries for HoneyHive observability and Pydantic AI.

```bash
pip install honeyhive pydantic-ai
```

--------------------------------

### Install AutoGen and HoneyHive Packages

Source: https://docs.honeyhive.ai/v2/integrations/autogen

Install the necessary packages for AutoGen, HoneyHive, and the OpenInference AutoGen AgentChat instrumentation.

```bash
pip install honeyhive autogen-agentchat autogen-ext[openai] \
    openinference-instrumentation-autogen-agentchat
```

--------------------------------

### Install DSPy and HoneyHive Dependencies

Source: https://docs.honeyhive.ai/v2/integrations/dspy

Install the necessary packages for DSPy, HoneyHive, and OpenInference instrumentation.

```bash
pip install honeyhive dspy openinference-instrumentation-dspy openinference-instrumentation-openai
```

--------------------------------

### Install HoneyHive SDK v1.0.1

Source: https://docs.honeyhive.ai/v2/sdk-reference/python-sdk-changelog

Install the HoneyHive Python SDK version 1.0.1 using pip.

```bash
pip install honeyhive==1.0.1
```

--------------------------------

### Example: Single Agent with Tools

Source: https://docs.honeyhive.ai/v2/integrations/langchain

Demonstrates setting up a LangChain agent with multiple tools (calculator and policy lookup) and integrating HoneyHive tracing. The agent is invoked with a query requiring both tool uses.

```python
import os
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.langchain import LangChainInstrumentor
from langchain.agents import create_agent
from langchain_core.tools import tool

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
LangChainInstrumentor().instrument(tracer_provider=tracer.provider)

@tool
def calculator(expression: str) -> str:
    """Evaluate a basic arithmetic expression."""
    return str(eval(expression, {"__builtins__": {}}, {}))

@tool
def policy_lookup(topic: str) -> str:
    """Look up company policy on a topic."""
    policies = {
        "soc2": "SOC 2 focuses on security, availability, processing integrity, confidentiality, and privacy.",
        "retention": "Default retention is 30 days unless compliance requires longer.",
    }
    return policies.get(topic.lower(), "No policy found.")

agent = create_agent(
    model="openai:gpt-4o-mini",
    tools=[calculator, policy_lookup],
    system_prompt="You are a support assistant. Use tools when needed.",
)

result = agent.invoke(
    {"messages": [{"role": "user", "content": "What is 17 * 3 + 5? Also summarize our SOC2 policy."}]}
)
print(result["messages"][-1].content)
```

--------------------------------

### Run HoneyHive Daemon

Source: https://docs.honeyhive.ai/v2/integrations/claude-code

Starts the daemon, installs hooks, and flushes queued events.

```bash
honeyhive-daemon run
```

--------------------------------

### Initialize Tracer and Create Session (Logger vs v1 SDK)

Source: https://docs.honeyhive.ai/v2/sdk-reference/python/migration/logger-to-v1

Compares how to start a session using the legacy logger and the v1 SDK. The v1 SDK requires initializing a tracer once and then creating sessions.

```python
import os
from honeyhive_logger import start

session_id = start(
    api_key=os.environ["HH_API_KEY"],
    project="support-bot",
    session_name="support-chat",
    source="production",
    inputs={"message": "How do I reset my password?"},
    metadata={"tenant_id": "acme"},
    user_properties={"user_id": "user-123"},
)
```

```python
from honeyhive import HoneyHiveTracer

# Reads HH_API_KEY and HH_SOURCE from the environment.
tracer = HoneyHiveTracer.init()

session_id = tracer.create_session(
    session_name="support-chat",
    inputs={"message": "How do I reset my password?"},
    metadata={"tenant_id": "acme"},
    user_properties={"user_id": "user-123"},
)
```

--------------------------------

### Verify HoneyHive SDK Installation Version (Alternative)

Source: https://docs.honeyhive.ai/v2/sdk-reference/python/migration/v0-to-v1

Use the importlib.metadata module to get the installed version of the honeyhive package. This method is useful if importing honeyhive directly raises an AttributeError, as was the case in v0.x.

```python
from importlib.metadata import version

print(version("honeyhive"))
```

--------------------------------

### End-to-End Session and Event Flow

Source: https://docs.honeyhive.ai/v2/sdk-reference/typescript-logger-to-api-sdk-migration

An example of starting a session, logging a model event, and then updating that event with its response and metadata.

```typescript
import { Client } from "@honeyhive/api-client";
import OpenAI from "openai";

const client = new Client();
const openai = new OpenAI();

const { session_id } = await client.sessions.create({
  session_name: "openai-example",
  source: "dev",
});

const startTime = Date.now();
const { event_id } = await client.events.create({
  session_id,
  event_type: "model",
  event_name: "chat-completion",
  config: { model: "gpt-4o-mini" },
  inputs: {
    messages: [{ role: "user", content: "What is the meaning of life?" }],
  },
});

const completion = await openai.chat.completions.create({
  model: "gpt-4o-mini",
  messages: [{ role: "user", content: "What is the meaning of life?" }],
});
const { content } = completion.choices[0].message;

if (content) {
  await client.events.update({
    event_id,
    outputs: { content },
    duration: Date.now() - startTime,
    metadata: { model: completion.model, usage: completion.usage },
  });
}
```

--------------------------------

### Complete Experiment Example

Source: https://docs.honeyhive.ai/v2/evaluation/concepts

Demonstrates how to set up and run an experiment using HoneyHive. This includes defining a dataset, a function to evaluate, and an evaluator function.

```python
from honeyhive import evaluate

dataset = [
    {"inputs": {"text": "I was charged twice"}, "ground_truth": {"intent": "billing"}},
    {"inputs": {"text": "App crashes on login"}, "ground_truth": {"intent": "technical"}},
]

def classify(datapoint):
    text = datapoint["inputs"]["text"]
    response = call_llm(f"Classify intent: {text}. Reply: billing, technical, account, or general.")
    return {"intent": response.strip().lower()}

def intent_match(outputs, inputs, ground_truth):
    return 1.0 if outputs.get("intent") == ground_truth.get("intent") else 0.0

result = evaluate(
    function=classify,
    dataset=dataset,
    evaluators=[intent_match],
    name="classifier-v1"
)
```

--------------------------------

### Create Session Request Example

Source: https://docs.honeyhive.ai/v2/sdk-reference/typescript/ref/sessions

Starts a new session. The server generates a UUIDv4 for session_id if omitted. Optional properties like event_name and source have server-side defaults.

```typescript
import { Honeyhive } from "@honeyhive/honeyhive";

const honeyhive = new Honeyhive("YOUR_API_KEY");

async function createSession() {
  const response = await honeyhive.sessions.create({
    session_name: "My first session",
    user_properties: {
      "user_id": "user-123",
      "plan": "free"
    }
  });
  console.log(response);
}

createSession();
```

--------------------------------

### Example: Creating and populating a dataset

Source: https://docs.honeyhive.ai/v2/sdk-reference/typescript

This example shows how to create a new dataset, append a datapoint linked to it, list all datasets in the project, and finally delete the created dataset.

```APIDOC
## Example: Creating and populating a dataset

### Description
This example shows how to create a new dataset, append a datapoint linked to it, list all datasets in the project, and finally delete the created dataset.

### Method
POST, GET, DELETE

### Endpoint
/datasets, /datapoints

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
##### client.datasets.create
- **name** (string) - Required - The name of the dataset.
- **description** (string) - Optional - A description for the dataset.

##### client.datapoints.create
- **inputs** (object) - Required - The input data for the datapoint.
  - **question** (string) - Required - The question for the QA pair.
- **ground_truth** (object) - Optional - The ground truth for the datapoint.
  - **answer** (string) - Required - The correct answer to the question.
- **linked_datasets** (array) - Optional - An array of dataset IDs to link this datapoint to.
  - **dataset_id** (string) - Required - The ID of the dataset.

##### client.datasets.delete
- **dataset_id** (string) - Required - The ID of the dataset to delete.

### Request Example
```typescript
import { Client } from '@honeyhive/api-client';

const client = new Client();

// 1. Create a dataset
const created = await client.datasets.create({
  name: 'qa-eval-set',
  description: 'Question/answer pairs for evaluation',
});
const datasetId = created.result.insertedId;

// 2. Append a datapoint linked to the new dataset
await client.datapoints.create({
  inputs: { question: 'What is the capital of France?' },
  ground_truth: { answer: 'Paris' },
  linked_datasets: [datasetId],
});

// 3. List datasets in the current project
const { datasets } = await client.datasets.list();
console.log(datasets.map((d) => d.name));

// 4. Delete the dataset
await client.datasets.delete({
  dataset_id: datasetId,
});
```

### Response
#### Success Response (200)
- **result.insertedId** (string) - The ID of the created dataset.
- **datasets** (array) - An array of dataset objects.
  - **name** (string) - The name of the dataset.

#### Response Example
```json
{
  "result": {
    "insertedId": "dts_abcdef123"
  },
  "datasets": [
    {
      "name": "qa-eval-set"
    }
  ]
}
```
```

--------------------------------

### Environment Variables Setup

Source: https://docs.honeyhive.ai/v2/tutorials/multi-agent-cookbook

Configure your HoneyHive, Google AI, and OpenAI API keys by creating a .env file.

```bash
HH_API_KEY=your-honeyhive-api-key
GOOGLE_API_KEY=your-google-ai-api-key
OPENAI_API_KEY=your-openai-key  # only needed for evaluate.py
```

--------------------------------

### Example: Multi-Agent Delegation with LangGraph and HoneyHive

Source: https://docs.honeyhive.ai/v2/integrations/langgraph

Demonstrates setting up a coordinator StateGraph that classifies customer questions and delegates to specialist agents. Includes tool definitions and LLM initialization for tracing.

```python
import os
from typing import Literal, TypedDict
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.langchain import LangChainInstrumentor
from langchain.agents import create_agent
from langchain_core.messages import HumanMessage, SystemMessage
from langchain_core.tools import tool
from langchain_openai import ChatOpenAI
from langgraph.graph import END, START, StateGraph
from pydantic import BaseModel, Field

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
LangChainInstrumentor().instrument(tracer_provider=tracer.provider)

model = ChatOpenAI(model="gpt-4o-mini")

@tool
def lookup_order_status(order_id: str) -> dict:
    """Look up the current status of a customer order."""
    statuses = {
        "ORD-1001": {"state": "shipped", "eta_days": 2},
        "ORD-1002": {"state": "processing", "eta_days": 5},
        "ORD-1003": {"state": "delayed", "eta_days": 8},
    }
    return statuses.get(order_id.upper(), {"state": "not_found"})

@tool
def lookup_policy(topic: str) -> dict:
    """Look up company support policy on a given topic."""
    policies = {
        "refund": {"summary": "Refunds within 30 days for undelivered or damaged items."},
        "cancellation": {"summary": "Cancellation allowed before shipment."},
        "shipping": {"summary": "Standard shipping 3-5 business days."},
    }
    return policies.get(topic.lower().strip(), {"summary": "No policy found."}))
```

--------------------------------

### Install and Initialize HoneyHive Daemon

Source: https://docs.honeyhive.ai/v2/integrations/claude-code

Install the honeyhive-daemon package and initialize its configuration files. This sets up the necessary local configuration for the daemon to run.

```bash
pip install honeyhive-daemon

# In your project repo
honeyhive-daemon init
# Creates .honeyhive/config.json and .honeyhive/config.local.json

export HH_API_KEY=<your HoneyHive API key>
export HH_API_URL=<your data plane URL>  # if not using default
honeyhive-daemon run
```

--------------------------------

### v1 SDK Example

Source: https://docs.honeyhive.ai/v2/sdk-reference/python/migration/logger-to-v1

Example demonstrating the equivalent functionality using the v1 SDK with a HoneyHiveTracer, @trace decorator, and session context manager. Ensure HH_API_KEY is set in the environment.

```python
from honeyhive import HoneyHiveTracer, trace

# Reads HH_API_KEY and HH_SOURCE from the environment.
tracer = HoneyHiveTracer.init()

@trace(event_name="model_inference", event_type="model", tracer=tracer)
def call_traced_model(message: str) -> str:
    response = call_model(message)
    tracer.enrich_span(metrics={"quality_score": score(response)})
    return response

def handle_chat(message: str, user_id: str) -> str:
    with tracer.with_session(
        session_name="support-chat",
        inputs={"message": message},
        user_properties={"user_id": user_id},
    ):
        response = call_traced_model(message)
        tracer.enrich_session(outputs={"response": response})
        return response
```

--------------------------------

### Install HoneyHive for OpenAI

Source: https://docs.honeyhive.ai/v2/integrations/openai

Install the necessary HoneyHive and OpenInference packages for OpenAI integration. You can install them together or separately.

```bash
pip install "honeyhive[openinference-openai]"

# Or install separately
pip install honeyhive openinference-instrumentation-openai openai
```

--------------------------------

### Install HoneyHive for Google ADK

Source: https://docs.honeyhive.ai/v2/integrations/google-adk

Install the HoneyHive package with the OpenInference Google ADK integration, or install them separately.

```bash
pip install "honeyhive[openinference-google-adk]"

# Or install separately
pip install honeyhive openinference-instrumentation-google-adk google-adk
```

--------------------------------

### Example: Math Assistant Agent with Plugin

Source: https://docs.honeyhive.ai/v2/integrations/semantic-kernel

Demonstrates creating a Semantic Kernel agent that uses a custom plugin to perform calculations. The agent is configured with OpenAI and its interactions are traced by HoneyHive.

```python
import asyncio
import os
from typing import Annotated

# Enable SK OTel before any imports
os.environ["SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS"] = "true"
os.environ["SEMANTICKERNEL_EXPERIMENTAL_GENAI_ENABLE_OTEL_DIAGNOSTICS_SENSITIVE"] = "true"

from honeyhive import HoneyHiveTracer
from openinference.instrumentation.openai import OpenAIInstrumentor

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))

instrumentor = OpenAIInstrumentor()
instrumentor.instrument(tracer_provider=tracer.provider)

from semantic_kernel.agents import ChatCompletionAgent
from semantic_kernel.connectors.ai.open_ai import OpenAIChatCompletion
from semantic_kernel.functions import kernel_function


class MathPlugin:
    @kernel_function(description="Evaluate a math expression")
    def calculate(
        self,
        expression: Annotated[str, "The math expression"]
    ) -> str:
        return str(eval(expression))


agent = ChatCompletionAgent(
    service=OpenAIChatCompletion(ai_model_id="gpt-4o-mini"),
    name="MathAssistant",
    instructions="Use the calculate function to solve math problems.",
    plugins=[MathPlugin()],
)


async def main():
    response = await agent.get_response(messages="What is 25 * 4?")
    print(response.content)


asyncio.run(main())
```

--------------------------------

### Install and Import Newer Google GenAI SDK

Source: https://docs.honeyhive.ai/v2/integrations/gemini

Install the recommended 'google-genai' SDK and use the correct import pattern for the OpenInference instrumentor. This ensures compatibility.

```bash
# Newer SDK (recommended)
pip install google-genai openinference-instrumentation-google-genai

# Import pattern
from google import genai
from openinference.instrumentation.google_genai import GoogleGenAIInstrumentor
```

--------------------------------

### Install HoneyHive for Anthropic

Source: https://docs.honeyhive.ai/v2/integrations/anthropic

Install the necessary HoneyHive and OpenInference packages for Anthropic integration. You can install them together or separately.

```bash
pip install "honeyhive[openinference-anthropic]"

# Or install separately
pip install honeyhive openinference-instrumentation-anthropic anthropic
```

--------------------------------

### Install HoneyHive CLI on macOS

Source: https://docs.honeyhive.ai/v2/cli-reference/getting-started

Installs the HoneyHive CLI using Homebrew on macOS. Ensure you have Homebrew installed.

```sh
brew tap honeyhiveai/tap
brew install honeyhive
```

--------------------------------

### Fetch Prompt and Log Config

Source: https://docs.honeyhive.ai/v2/tracing/configuration-details

This example demonstrates fetching a deployed prompt using HoneyHive's API and logging its configuration details, including name, ID, model, and temperature, onto the trace.

```python
import os
from openai import OpenAI
from honeyhive import HoneyHive, HoneyHiveTracer, enrich_span, trace

hh = HoneyHive(api_key=os.environ["HH_API_KEY"])
tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
openai_client = OpenAI()

# Fetch the deployed prompt
configs = hh.configurations.list()
prompt = next(
    (c.model_dump() for c in configs
     if c.model_dump().get("name") == "my-prompt"
     and "prod" in c.model_dump().get("env", [])),
    None,
)

@trace
def chat(user_message: str):
    if not prompt:
        raise ValueError("Prompt not found")

    params = prompt["parameters"]

    # Log which config produced this response
    enrich_span(config={
        "prompt_name": prompt["name"],
        "prompt_id": prompt.get("id"),
        "model": params["model"],
        "temperature": params.get("hyperparameters", {}).get("temperature"),
    })

    messages = params["template"] + [{"role": "user", "content": user_message}]
    response = openai_client.chat.completions.create(
        model=params["model"],
        messages=messages,
        **params.get("hyperparameters", {}),
    )
    return response.choices[0].message.content

chat("Explain quantum computing simply.")
```

--------------------------------

### Example: Multi-Provider Completions with LiteLLM

Source: https://docs.honeyhive.ai/v2/integrations/litellm

Demonstrates making completion calls to different LLM providers (OpenAI and Anthropic) through LiteLLM. All calls are automatically traced by HoneyHive.

```python
import os
import litellm
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.litellm import LiteLLMInstrumentor

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
LiteLLMInstrumentor().instrument(tracer_provider=tracer.provider)

# OpenAI via LiteLLM
response = litellm.completion(
    model="openai/gpt-4o-mini",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "What is the capital of France?"},
    ],
    max_tokens=50,
)
print(response.choices[0].message.content)

# Anthropic via LiteLLM - same interface, automatically traced
response2 = litellm.completion(
    model="anthropic/claude-haiku-4-5-20251001",
    messages=[
        {"role": "user", "content": "Tell me a fun fact about Paris."},
    ],
    max_tokens=100,
)
print(response2.choices[0].message.content)
```

--------------------------------

### Install HoneyHive with Strands Support

Source: https://docs.honeyhive.ai/v2/integrations/strands

Install the necessary packages for HoneyHive and Strands Agents. This can be done as a combined installation or separately.

```bash
pip install "honeyhive[aws-strands]"

# Or install separately
pip install honeyhive strands-agents
```

--------------------------------

### Create Dataset and Append Datapoint

Source: https://docs.honeyhive.ai/v2/cli-reference

Example of creating a dataset with a name and description, then capturing its ID. This is the first step in managing datasets and their contents.

```json
{
  "inputs": { "question": "What is the capital of France?" },
  "ground_truth": { "answer": "Paris" }
}
```

```bash
# 1. Create the dataset and capture its ID from the response.
DATASET_ID=$(honeyhive datasets create \
  --name "qa-eval-set" \
  --description "Question/answer pairs for evaluation" \
  | jq -r '.result.insertedId')
```

--------------------------------

### Example: Single Agent with HoneyHive Tracing

Source: https://docs.honeyhive.ai/v2/integrations/google-adk

Demonstrates tracing a single agent in a Google ADK application. This example sets up a weather agent, initializes the HoneyHive tracer, instruments the ADK, and runs the agent, capturing its execution details.

```python
import asyncio
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.google_adk import GoogleADKInstrumentor
from google.adk.agents import Agent
from google.adk.runners import InMemoryRunner
from google.genai.types import Content, Part

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
GoogleADKInstrumentor().instrument(tracer_provider=tracer.provider)

def get_weather(city: str) -> dict:
    return {"report": f"Weather in {city}: 20°C, clear"}

agent = Agent(
    name="weather_agent",
    model="gemini-2.0-flash",
    description="Answers weather questions.",
    instruction="Use get_weather to answer weather questions.",
    tools=[get_weather],
)

async def main():
    runner = InMemoryRunner(agent=agent, app_name="app")
    session_id = tracer.session_id  # Use HoneyHive session ID
    await runner.session_service.create_session(app_name="app", user_id="user", session_id=session_id)
    
    msg = Content(role="user", parts=[Part(text="What's the weather in Tokyo?")])
    async for event in runner.run_async(user_id="user", session_id=session_id, new_message=msg):
        if event.is_final_response():
            print(event.content.parts[0].text)

asyncio.run(main())
```

--------------------------------

### Install HoneyHive SDK v1.0.0rc20

Source: https://docs.honeyhive.ai/v2/sdk-reference/python-sdk-changelog

Install the HoneyHive SDK version 1.0.0rc20. This command is used for updating or installing a specific version of the SDK.

```bash
pip install honeyhive==1.0.0rc20
```

--------------------------------

### Install and Import New SDK

Source: https://docs.honeyhive.ai/v2/sdk-reference/typescript-logger-to-api-sdk-migration

Uninstall the old logger and install the new API client. Then, import the Client class and instantiate it. The client automatically reads the HH_API_KEY from environment variables.

```bash
npm uninstall @honeyhive/logger
npm install @honeyhive/api-client
```

```typescript
import { Client } from "@honeyhive/api-client";

const client = new Client(); // reads HH_API_KEY from env
```

--------------------------------

### Install HoneyHive SDK v1.0.0rc21

Source: https://docs.honeyhive.ai/v2/sdk-reference/python-sdk-changelog

Install the HoneyHive SDK version 1.0.0rc21. This command is used for updating or installing a specific version of the SDK.

```bash
pip install honeyhive==1.0.0rc21
```

--------------------------------

### Install HoneyHive SDK v1.0.0rc22

Source: https://docs.honeyhive.ai/v2/sdk-reference/python-sdk-changelog

Install the HoneyHive SDK version 1.0.0rc22. This command is used for updating or installing a specific version of the SDK.

```bash
pip install honeyhive==1.0.0rc22
```

--------------------------------

### Install LiteLLM Integration

Source: https://docs.honeyhive.ai/v2/changelog

Install the LiteLLM integration for tracing completion, acompletion, and embedding calls across various providers. This requires the OpenInference library.

```bash
pip install "honeyhive[openinference-litellm]"
```

--------------------------------

### Install HoneyHive with Traceloop Azure OpenAI

Source: https://docs.honeyhive.ai/v2/integrations/azure_openai

Install the HoneyHive package with Traceloop and Azure OpenAI support. Alternatively, install the packages separately.

```bash
pip install "honeyhive[traceloop-azure-openai]"

# Or install separately
pip install honeyhive opentelemetry-instrumentation-openai openai azure-identity
```

--------------------------------

### Initialize and Query Claude Agent SDK

Source: https://docs.honeyhive.ai/v2/integrations/claude-agent-sdk

Demonstrates how to initialize the Claude SDK client with specific options and perform multi-turn queries, capturing each turn as a separate span in HoneyHive.

```python
from claude_agent_sdk import (
    AssistantMessage,
    ClaudeAgentOptions,
    ClaudeSDKClient,
    TextBlock,
)
import asyncio
from honeyhive import HoneyHiveTracer
from openinference.instrumentation.claude_agent_sdk import ClaudeAgentSDKInstrumentor

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
ClaudeAgentSDKInstrumentor().instrument(tracer_provider=tracer.provider)

async def main():
    client = ClaudeSDKClient(
        options=ClaudeAgentOptions(
            system_prompt="You are a customer support agent. Keep responses concise.",
            allowed_tools=["Read"],
            max_turns=3,
            permission_mode="bypassPermissions",
        )
    )

    await client.connect()
    try:
        # Turn 1
        await client.query(prompt="Read orders.json and tell me the status of ORD-1002.")
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(block.text)

        # Turn 2 - agent remembers context from Turn 1
        await client.query(prompt="What about ORD-1003? Is it delayed?")
        async for message in client.receive_response():
            if isinstance(message, AssistantMessage):
                for block in message.content:
                    if isinstance(block, TextBlock):
                        print(block.text)
    finally:
        await client.disconnect()
        tracer.force_flush()

asyncio.run(main())
```

--------------------------------

### Install honeyhive v1 package

Source: https://docs.honeyhive.ai/v2/sdk-reference/python/migration/honeyhive-bundled-to-v1

Uninstall the bundled package and install the stable v1 package. If you use extras, install the matching extras on `honeyhive`.

```bash
pip uninstall honeyhive-bundled -y
pip install "honeyhive>=1.0.0"
```

```bash
pip install "honeyhive[openinference-openai]"
pip install "honeyhive[openinference-anthropic]"
pip install "honeyhive[openinference-langchain]"
```

```bash
pip install "honeyhive[traceloop-openai]"
pip install "honeyhive[traceloop-anthropic]"
pip install "honeyhive[traceloop-aws-bedrock]"
```

--------------------------------

### Install HoneyHive and Datasets Libraries

Source: https://docs.honeyhive.ai/v2/datasets/hf-datasets

Install the necessary Python libraries for HoneyHive and Hugging Face Datasets. This is a prerequisite for importing data.

```bash
pip install honeyhive datasets
```

--------------------------------

### Install HoneyHive with Traceloop for Anthropic

Source: https://docs.honeyhive.ai/v2/integrations/anthropic

Install the HoneyHive package with Traceloop and Anthropic support. This command installs the necessary dependencies for integrating HoneyHive with Anthropic via Traceloop.

```bash
pip install "honeyhive[traceloop-anthropic]"
```

--------------------------------

### Diagnose HoneyHive Installation

Source: https://docs.honeyhive.ai/v2/integrations/claude-code

Checks if hooks and configuration are correctly installed.

```bash
honeyhive-daemon doctor
```

--------------------------------

### Example: Multi-Turn Conversation with Claude Agent SDK

Source: https://docs.honeyhive.ai/v2/integrations/claude-agent-sdk

Illustrates setting up a multi-turn conversation using `ClaudeSDKClient`, which maintains session context across interactions. The tracer and instrumentor should be initialized beforehand.

```python
import asyncio
import os
from openinference.instrumentation.claude_agent_sdk import ClaudeAgentSDKInstrumentor
from honeyhive import HoneyHiveTracer

tracer = HoneyHiveTracer.init(api_key=os.getenv("HH_API_KEY"))
ClaudeAgentSDKInstrumentor().instrument(tracer_provider=tracer.provider)


```
Tokens:
Raw