Skip to content

SDK Explanation

Deep-dive documentation explaining SDK architecture and design.

Architecture

SDK Architecture - Pack-first design and components
Observability - Event system and monitoring

Design Philosophy

Pack-First Architecture

The SDK is built around the pack file as the single source of truth:

Diagram

Why Pack-First?

Reduced Boilerplate - No manual provider/manager setup
Tested Configuration - Packs are validated by Arena
Portable - Same pack works across environments
Versioned - Pack files are version controlled

Minimal API

conv, _ := sdk.Open("./pack.json", "chat")
defer conv.Close()
resp, _ := conv.Send(ctx, "Hello")

Three lines to a working conversation.

Key Concepts

Conversation Lifecycle

Open - sdk.Open() loads pack, creates conversation
Configure - SetVar(), OnTool() setup
Use - Send(), Stream() interactions
Close - Close() cleanup

Tool Execution

Tools are registered with handlers:

LLM Request
    │
    ▼
Tool Call Decision
    │
    ▼
Handler Lookup
    │
    ├─► OnTool handler → Execute immediately
    │
    └─► OnToolAsync handler
            │
            ├─► Auto-approve → Execute
            │
            └─► Pending → Wait for ResolveTool/RejectTool

Event System

Events flow through the hooks package:

Send() ─────► EventSend
    │
    ▼
Provider Call
    │
    ▼
Response ───► EventResponse
    │
    ├─► Tool Call ───► EventToolCall
    │       │
    │       ▼
    │   Handler
    │       │
    │       ▼
    │   EventToolResult
    │
    └─► Error ───► EventError

See Also