Hone Python SDK

hone is the Python SDK for Hone, an AI-agent observability platform. Use it to capture agent conversations and MCP tool calls and send them to Hone's ingestion edge.

Install

uv add hone
# with MCP tool-call capture:
uv add "hone[mcp]"

Configuration

The SDK reads its configuration from arguments or the environment:

API keys look like sk_<hex>. For local development, point the endpoint at http://localhost:8080.

Quick start

import honeai

honeai.init("sk_...")  # or rely on HONE_API_KEY

# A single turn you want to time and enrich:
turn = honeai.begin(user_id="user-123", agent_name="support-bot", input="How do I reset my password?")
turn.set_property("channel", "web")
turn.set_properties({"tier": "pro"})
turn.end("Head to Settings > Security to reset it.")

begin starts a new conversation (a fresh session_id) and records the start time. end posts a capture-session (once per new conversation) plus a capture-event with an auto-computed latency.

One-shot capture

honeai.track(
    user_id="user-123",
    input="What's my balance?",
    output="Your balance is $42.",
    agent_name="finance-bot",
)

Group several turns into one conversation by passing a shared conversation_id:

convo = "9f8b..."  # any stable id
honeai.track(user_id="u1", input="hi", output="hello", agent_name="bot", conversation_id=convo)
honeai.track(user_id="u1", input="bye", output="see you", agent_name="bot", conversation_id=convo)

User traits

Register traits that decorate the user's next session:

honeai.identify("user-123", {"plan": "enterprise", "name": "Ada"})
honeai.begin(user_id="user-123", agent_name="bot", input="hi").end("hello")
# ^ the session's user_data carries plan + name

MCP tool-call capture

Wrap a FastMCP server so every tool call is captured as a TOOL event:

from mcp.server.fastmcp import FastMCP
import honeai.mcp

server = FastMCP("my-server")

@server.tool()
def add(a: int, b: int) -> int:
    return a + b

honeai.init("sk_...")
honeai.mcp.track(server)  # instruments the server in place

Pass disable_input=True and/or disable_output=True to omit tool arguments or return values from the captured events. mcp is an optional dependency; if it is not installed, honeai.mcp.track logs a warning and returns the server unchanged.

Error handling

Network and HTTP failures never raise into your hot path by default — they are logged (via the hone logger) and dropped. For tests, construct a client with raise_on_error=True:

from honeai.client import Client
client = Client("sk_test", raise_on_error=True)

Development

uv sync
uv run pytest
uv run ruff check