> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usehone.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> Complete reference for the Hone Python SDK: init, begin, end, track, identify, set_property, and conversation grouping, with runnable examples.

The Python SDK instruments your agent from application code. Install it with `pip install honeai` and configure it once at startup.

## init

Configure the SDK with your API key. Call it once, early, before any other Hone call.

```python theme={null}
import honeai

honeai.init("sk_your_key_here")
```

Pass `endpoint` to target a non-default base URL, such as a local stack:

```python theme={null}
honeai.init("sk_your_key_here", endpoint="http://localhost:8080")
```

<Note>
  Load the key from the environment rather than hard-coding it: `honeai.init(os.environ["HONE_API_KEY"])`. See [Authentication](/authentication).
</Note>

## begin and end

`begin()` opens an interaction for a single agent turn and returns an object you close with `end()`. This is the most explicit way to record a turn, and it captures latency automatically from the time between the two calls.

```python theme={null}
interaction = honeai.begin(
    user_id="user_8f21",
    agent_name="support-bot",
    input="How do I reset my password?",
)

reply = run_agent("How do I reset my password?")

interaction.end(reply, success=True)
```

**`begin` parameters**

| Parameter    | Type   | Required | Description                               |
| ------------ | ------ | -------- | ----------------------------------------- |
| `user_id`    | string | Yes      | Pseudonymous identifier for the end user. |
| `agent_name` | string | Yes      | Name of the agent handling this turn.     |
| `input`      | string | Yes      | The user's message for this turn.         |

**`end` parameters**

| Parameter | Type   | Required | Description                                     |
| --------- | ------ | -------- | ----------------------------------------------- |
| `output`  | string | Yes      | The agent's reply.                              |
| `success` | bool   | No       | Whether the turn succeeded. Defaults to `true`. |

Mark a failed turn so it surfaces in error analytics:

```python theme={null}
try:
    reply = run_agent(user_input)
    interaction.end(reply, success=True)
except Exception as err:
    interaction.end(str(err), success=False)
```

## track

`track()` records a completed turn in a single call. Reach for it when you already have both the input and the output in hand and do not need to hold an interaction open.

```python theme={null}
honeai.track(
    user_id="user_8f21",
    input="How do I reset my password?",
    output="Head to Settings, then Security, and choose Reset password.",
    agent_name="support-bot",
    conversation_id="conv_5c19",
)
```

**Parameters**

| Parameter         | Type   | Required | Description                                 |
| ----------------- | ------ | -------- | ------------------------------------------- |
| `user_id`         | string | Yes      | Pseudonymous end-user identifier.           |
| `input`           | string | Yes      | The user's message.                         |
| `output`          | string | Yes      | The agent's reply.                          |
| `agent_name`      | string | No       | Name of the agent.                          |
| `conversation_id` | string | No       | Groups related turns into one conversation. |

## Conversation grouping

A conversation is a series of turns between one user and your agent. Pass the same `conversation_id` across `track()` calls to thread them together, so the dashboard shows them as one exchange under **User Stories** rather than as isolated turns.

```python theme={null}
conversation_id = "conv_5c19"

honeai.track(
    user_id="user_8f21",
    input="How do I reset my password?",
    output="Head to Settings, then Security, and choose Reset password.",
    conversation_id=conversation_id,
)

honeai.track(
    user_id="user_8f21",
    input="I don't see a Security tab.",
    output="It's under your profile menu on the top right.",
    conversation_id=conversation_id,
)
```

Generate a fresh id when a new conversation starts, and reuse it for every follow-up turn in that exchange.

## identify

`identify()` attaches traits to a user id. Traits enrich the user profile in the dashboard and become dimensions you can filter and segment on. Keep the id pseudonymous and avoid putting raw personal data in the traits.

```python theme={null}
honeai.identify("user_8f21", {
    "plan": "enterprise",
    "signup_cohort": "2026-Q2",
    "region": "eu-west",
})
```

## set\_property and set\_properties

Within an open interaction, attach custom properties such as the model used, token counts, or cost. These ride along on the event and power metadata-driven charts and filters.

```python theme={null}
interaction = honeai.begin(
    user_id="user_8f21",
    agent_name="support-bot",
    input="Summarize this thread.",
)

interaction.set_property("model", "claude-sonnet-4")

interaction.set_properties({
    "input_tokens": 1840,
    "output_tokens": 220,
    "cost_usd": 0.0142,
})

interaction.end(reply, success=True)
```

Use `set_property` for a single key and `set_properties` to attach several at once. Define the corresponding keys under **Settings → Metadata Keys** so they become selectable dimensions in the dashboard.

## Full example

```python theme={null}
import os
import honeai

honeai.init(os.environ["HONE_API_KEY"])

honeai.identify("user_8f21", {"plan": "enterprise", "region": "eu-west"})

interaction = honeai.begin(
    user_id="user_8f21",
    agent_name="support-bot",
    input="How do I export my data?",
)

interaction.set_property("model", "claude-sonnet-4")

reply = "Open Settings, choose Export, and pick a format. We'll email a link."
interaction.set_properties({"output_tokens": 96, "cost_usd": 0.0031})

interaction.end(reply, success=True)
```

<Note>
  To capture MCP tool, resource, and prompt calls automatically, see [MCP](/mcp).
</Note>