Python SDK

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.

import honeai

honeai.init("sk_your_key_here")

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

honeai.init("sk_your_key_here", endpoint="http://localhost:8080")

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

Deployment stage (dev / staging / prod)

Tag every event from a process with its deployment stage so the dashboard can separate real production traffic from dev and staging. The Stage filter on the reliability scorecard, cost views, and triage all read it, and the scorecard defaults to production so dev noise never skews your reliability numbers. Set it once at init, or per-deploy from the HONE_ENV environment variable:

honeai.init("sk_your_key_here", environment="production")
# or, per-deploy, from the environment:
#   HONE_ENV=staging

Argument	Environment	Default
`honeai.init(environment=)`	`HONE_ENV`	— (no stage tag)

The value is written to metadata["environment"] on every event and canonicalized case-insensitively at write time: prod / PROD / prd → production, stg → staging, local / development → dev. Any other value is kept as-is (lowercased), so a custom stage like qa is never folded into the wrong bucket. The explicit init argument wins over HONE_ENV.

Leave both unset and no stage tag is written — the scorecard then shows a “Tag traffic” banner. You can also set the stage on an individual turn with interaction.set_property("environment", "staging"), which overrides the process-wide value.

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.

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.
`customer_id`	string	No	Downstream tenant when one agent serves several of your customers — see Multi-tenant.

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:

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.

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.
`customer_id`	string	No	Downstream tenant when one agent serves several of your customers — see Multi-tenant.

Multi-tenant (customer_id)

When one agent serves several of your own customers, pass customer_id so each session and event is scoped to the downstream tenant it belongs to. The end-user’s identity becomes the pair (customer_id, user_id), and the dashboard can filter and roll up per customer.

# On an explicit turn:
turn = honeai.begin(
    user_id="user-123",
    agent_name="support-bot",
    input="How do I reset my password?",
    customer_id="acme-corp",
)
turn.end("Head to Settings → Security.")

# Or in one shot:
honeai.track(
    user_id="user-123",
    input="How do I reset my password?",
    output="Head to Settings → Security.",
    agent_name="support-bot",
    customer_id="acme-corp",
)

customer_id is a first-class field — pass it as the argument, not via set_property, so per-customer scoping and rollups work. It is stamped on the session and every event of the turn. Omit it entirely for single-tenant agents.

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.

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.

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.

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

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)

To capture MCP tool, resource, and prompt calls automatically, see MCP.

Get started

SDKs

Integrations

Platform

init

Deployment stage (dev / staging / prod)

begin and end

track

Multi-tenant (customer_id)

Conversation grouping

identify

set_property and set_properties

Full example

​init

​Deployment stage (dev / staging / prod)

​begin and end

​track

​Multi-tenant (customer_id)

​Conversation grouping

​identify

​set_property and set_properties

​Full example

init

Deployment stage (dev / staging / prod)

begin and end

track

Multi-tenant (customer_id)

Conversation grouping

identify

set_property and set_properties

Full example