Kivviq SDK

Python SDK for Kivviq — execution observability for AI agents.

Kivviq helps developers see what happens inside their AI agents by capturing and tracing agent executions.

Installation

Install the SDK:

pip install kivviq

For OpenAI auto-instrumentation:

pip install "kivviq[openai]"

Quick Start

from kivviq import Kivviq

# Initialize Kivviq
kivviq = Kivviq(api_key="YOUR_KIVVIQ_API_KEY")

# Trace your agent
@kivviq.trace
def my_agent():
    # Your agent logic goes here
    return "Hello from my AI agent!"

# Execute your agent
result = my_agent()

print(result)

# Close the SDK connection
kivviq.close()

Replace YOUR_KIVVIQ_API_KEY with your actual API key.

Configuration

Kivviq supports the following configuration options:

You can also configure these using environment variables:

KIVVIQ_API_KEY=your_api_key
KIVVIQ_BACKEND_URL=https://kivviq.ethiodeploy.app

The SDK automatically loads environment variables from a .env file when available.

What Gets Captured

Kivviq captures execution information including:

• Run start and end times
• Run duration
• Execution status (success or error)
• Error messages and types
• OpenAI calls, when OpenAI instrumentation is enabled
• Events logged manually through the SDK

Event Types

Kivviq supports the following event types:

from kivviq.event import EventType

EventType.LLM_CALL
EventType.TOOL_CALL
EventType.USER_INPUT
EventType.OUTPUT
EventType.ERROR

Reliability

• Your agent continues running if the Kivviq backend is unreachable.
• Exceptions from your agent are re-raised rather than swallowed.
• Selected GET and PATCH requests retry transient failures once.
• POST requests are not automatically retried.
• Instrumentation hooks are cleaned up after execution.

Full Documentation

See the SDK documentation for the complete reference.