Skip to content
pigo

Start here

Overview

What pi-go is, the six-layer stack, and the shortest path to a working call

Read this when
  • Arriving at the documentation for the first time
  • Deciding which layer of the SDK to build against
  • Looking for the boundary between these docs and the API reference

You can build from one model call to a durable agent product with pi-go.

pi-go is a Go SDK for AI agents. It keeps provider wire formats below stable Go types. You choose the layer that matches your control needs.

The stack

The stack is a set of layers, not a framework that owns your application. Start at pkg/pi when defaults fit. Move down when you need explicit providers, custom loops, durable sessions, or direct model calls.

pkg/catalog · pipkg/harnesspkg/durable · sessionpkg/agentpkg/ai
The stack

Each layer uses the ones below it, and none of them use you. From the top: pkg/pi is one import with providers auto-wired from the environment; pkg/catalog is your registry of providers, models, and agent kinds; pkg/harness compiles definitions, skills, and instructions into loop mechanics; pkg/durable and pkg/session keep persistent transcripts you can branch, fork, and compact; pkg/agent is the loop; pkg/ai is one call.

Your first call

Set OPENAI_API_KEY before you run it.

package main


import (
  "context"
  "fmt"
  "log"


  "github.com/sonnes/pi-go/pkg/ai"
  "github.com/sonnes/pi-go/pkg/pi"
)


func main() {
  msg, err := pi.GenerateText(
    context.Background(),
    "openai-completions/gpt-5-mini",
    ai.Prompt{Messages: []ai.Message{ai.UserMessage("Say hello in one sentence.")}},
  )
  if err != nil {
    log.Fatal(err)
  }
  fmt.Println(msg.JoinText(""))
}

How to read these docs

  • The layers - Read these for the mental model, from pkg/ai up to pkg/pi.
  • How to - Use these guides when you want task-first examples.
  • Advanced - Read concept pages when a layer page leaves a design choice compressed.
  • GoDoc - Use API reference for exact signatures and field details.

Conventions on these pages

The YAML frontmatter powers the documentation index. The summary field names the page promise. The read_when list names the moment to open the page.

These pages explain why the SDK has its shape. GoDoc owns exhaustive API detail. When a page names an identifier, it gives you the mental model and then moves on.