AgentSkillsCN

python-sdk

为Opik构建Python SDK模式。当在sdks/python中工作、开发SDK API、进行集成，或处理消息时，可使用此技能。

SKILL.md
--- frontmatter
name: python-sdk
description: Python SDK patterns for Opik. Use when working in sdks/python, on SDK APIs, integrations, or message processing.

Python SDK

Three-Layer Architecture

code
Layer 1: Public API      (opik.Opik, @opik.track)
    ↓
Layer 2: Message Processing   (queue, batching, retry)
    ↓
Layer 3: REST Client     (OpikApi, HTTP)

Critical Gotchas

Flush Before Exit

python
# ✅ REQUIRED for async operations
client = opik.Opik()
# ... tracing operations ...
client.flush()  # Must call before exit!

Async vs Sync Operations

Async (via message queue) - fire-and-forget:

  • •trace(), span()
  • •log_traces_feedback_scores()
  • •experiment.insert()

Sync (blocking, returns data):

  • •create_dataset(), get_dataset()
  • •create_prompt(), get_prompt()
  • •search_traces(), search_spans()

Lazy Imports for Integrations

python
# ✅ GOOD - integration files assume dependency exists
import anthropic  # Only imported when user uses integration

# ❌ BAD - importing at package level
from opik.integrations import anthropic  # Would fail if not installed

Integration Patterns

Pattern Selection

code
Library has callbacks? → Pure Callback (LangChain, LlamaIndex)
No callbacks?         → Method Patching (OpenAI, Anthropic)
Callbacks unreliable? → Hybrid (ADK)

Method Patching (OpenAI, Anthropic)

python
from opik.integrations.anthropic import track_anthropic

client = anthropic.Anthropic()
tracked_client = track_anthropic(client)  # Wraps methods

Callback-Based (LangChain)

python
from opik.integrations.langchain import OpikTracer

tracer = OpikTracer()
chain.invoke(input, config={"callbacks": [tracer]})

Decorator-Based

python
@opik.track
def my_function(input: str) -> str:
    # Auto-creates span, captures input/output
    return process(input)

Dependency Policy

  • •Avoid adding new dependencies
  • •Use conditional imports for integrations
  • •Keep version bounds flexible: >=2.0.0,<3.0.0

Batching System

Messages batch together for efficiency:

  • •Flush triggers: time (1s), size (100), memory (50MB), manual
  • •Reduces HTTP overhead significantly

API Method Naming

python
# CRUD: create/get/list/update/delete
client.create_experiment(name="exp")
client.get_dataset(name="ds")

# Search for complex queries
client.search_spans(project_name="proj")
client.search_traces(project_name="proj")

# Batch for bulk operations
client.batch_create_items(...)

Reference Files