Conversation

The main type for interacting with LLMs in SDK v2.

Creating a Conversation

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

Methods

Send

Send a message and wait for response.

func (c *Conversation) Send(ctx context.Context, message any) (*Response, error)

Example:

resp, err := conv.Send(ctx, "Hello!")
if err != nil {
    return err
}
fmt.Println(resp.Text())

Stream

Stream a response in real-time.

func (c *Conversation) Stream(ctx context.Context, message string) <-chan StreamChunk

Example:

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

SetVar / GetVar

Manage template variables.

func (c *Conversation) SetVar(key string, value any)
func (c *Conversation) GetVar(key string) any
func (c *Conversation) SetVars(vars map[string]any)

Example:

conv.SetVar("user_name", "Alice")
name := conv.GetVar("user_name")

OnTool / OnToolCtx

Register tool handlers.

func (c *Conversation) OnTool(name string, handler ToolHandler)
func (c *Conversation) OnToolCtx(name string, handler ToolHandlerCtx)
func (c *Conversation) OnTools(handlers map[string]ToolHandler)

Example:

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

OnToolAsync

Register tool with approval workflow.

func (c *Conversation) OnToolAsync(
    name string,
    check func(map[string]any) tools.PendingResult,
    execute ToolHandler,
)

Example:

conv.OnToolAsync("process_refund",
    func(args map[string]any) tools.PendingResult {
        if args["amount"].(float64) > 100 {
            return tools.PendingResult{
                Reason: "high_value",
                Message: "Requires approval",
            }
        }
        return tools.PendingResult{}
    },
    func(args map[string]any) (any, error) {
        return map[string]any{"status": "done"}, nil
    },
)

OnToolHTTP

Register HTTP-based tool.

func (c *Conversation) OnToolHTTP(name string, config *tools.HTTPToolConfig)

Subscribe

Subscribe to events.

func (c *Conversation) Subscribe(event string, handler func(hooks.Event))

ResolveTool / RejectTool

Handle pending approvals.

func (c *Conversation) ResolveTool(id string) (*ToolResult, error)
func (c *Conversation) RejectTool(id string, reason string) (*ToolResult, error)

Messages

Get conversation history.

func (c *Conversation) Messages() []types.Message

Clear

Clear conversation history.

func (c *Conversation) Clear()

Fork

Create an isolated copy.

func (c *Conversation) Fork() *Conversation

Close

Close and clean up.

func (c *Conversation) Close() error

ID

Get conversation identifier.

func (c *Conversation) ID() string

Thread Safety

All methods are thread-safe for concurrent use.

See Also