SDK v2 How-To Guides

Practical, task-focused guides for common SDK operations.

Getting Started

• Open a Conversation - Use sdk.Open() to get started
• Send Messages - Send messages with Send() and Stream()

Tools & Functions

• Register Tools - Add tools with OnTool()
• HTTP Tools - External API calls with OnToolHTTP()
• HITL Workflows - Approval with OnToolAsync()

Variables & Templates

• Manage Variables - Use SetVar() and GetVar()

Context Management

• Manage Context - Configure token budgets and relevance-based truncation

Observability

• Monitor Events - Subscribe to events with Subscribe()

Quick Reference

Open a Conversation

conv, err := sdk.Open("./app.pack.json", "assistant")
if err != nil {
    log.Fatal(err)
}
defer conv.Close()

Send Message

resp, err := conv.Send(ctx, "Hello!")
fmt.Println(resp.Text())

Stream Response

for chunk := range conv.Stream(ctx, "Tell me a story") {
    if chunk.Type == sdk.ChunkDone {
        break
    }
    fmt.Print(chunk.Text)
}

Register Tool

conv.OnTool("get_time", func(args map[string]any) (any, error) {
    return time.Now().Format(time.RFC3339), nil
})

Set Variables

conv.SetVar("user_name", "Alice")
conv.SetVars(map[string]any{
    "role":     "admin",
    "language": "en",
})

Subscribe to Events

conv.Subscribe(hooks.EventSend, func(e hooks.Event) {
    log.Printf("Sent: %v", e.Data["message"])
})

By Use Case

Building a Chatbot

1. Open a Conversation
2. Send Messages
3. Manage Variables

Adding Function Calling

1. Register Tools
2. HTTP Tools (for external APIs)

Building Safe AI Agents

1. HITL Workflows
2. Monitor Events

See Also

• Tutorials - Step-by-step learning
• Reference Documentation - API reference
• Examples - Working code examples