Examples

Run these commands from the repository root. Examples requiring a model use your own provider credentials and may incur charges.

Quick Start

go run ./example/quickstart

Set OPENAI_API_KEY and AGENT_MODEL. The full tutorial explains optional compatible-service configuration.

CLI Chat

go run ./example/cli-chat

The CLI demonstrates tools, specialist handoffs, streaming, model selection, skills, and conversation management. Inspect the example source for provider-specific environment variables and optional persistence settings.

A2A Server and Client

Run the server in one terminal and the client in another:

go run ./example/a2a-server

go run ./example/a2a-client

The server uses a stub provider, so it needs no model key. It listens on port 8080 by default; PORT overrides the server port. See the client source for its target URL options when changing the port.

Complete server source

package main

import (
	"context"
	"fmt"
	"log"
	"os"

	"github.com/covoyage/covonaut/agentcore"
	"github.com/covoyage/covonaut/a2a"
)

// stubProvider is a minimal provider for demonstration purposes.
type stubProvider struct{}

func (stubProvider) Complete(ctx context.Context, req *agentcore.ProviderRequest) (*agentcore.ProviderResponse, error) {
	return &agentcore.ProviderResponse{
		Content: "Hello! I'm a demo A2A agent.",
	}, nil
}

func (stubProvider) Stream(ctx context.Context, req *agentcore.ProviderRequest) (<-chan agentcore.StreamDelta, error) {
	ch := make(chan agentcore.StreamDelta, 1)
	ch <- agentcore.StreamDelta{Content: "Hello! I'm a demo A2A agent."}
	close(ch)
	return ch, nil
}

func main() {
	if err := run(); err != nil {
		log.Fatal(err)
	}
}

func run() error {
	port := os.Getenv("PORT")
	if port == "" {
		port = "8080"
	}

	cfg := agentcore.Config{
		ModelConfig: agentcore.ModelConfig{
			Name:     "demo-a2a-agent",
			Model:    "stub",
			Provider: stubProvider{},
		},
		SystemPrompt: "You are a helpful demo agent exposed via the A2A protocol.",
	}

	// Create a simple agent
	agent, err := agentcore.NewWithError(cfg)
	if err != nil {
		return err
	}
	defer agent.Close()

	// Define agent card
	card := a2a.AgentCard{
		Name:        "demo-a2a-agent",
		Description: "A demonstration A2A agent built with Covonaut",
		URL:         fmt.Sprintf("http://localhost:%s", port),
		Version:     "1.0.0",
		Capabilities: a2a.AgentCapabilities{
			Streaming:         true,
			PushNotifications: false,
		},
		Skills: []a2a.AgentSkill{
			{
				ID:          "echo",
				Name:        "Echo",
				Description: "Echo back the user's message",
				Tags:        []string{"demo", "echo"},
			},
			{
				ID:          "greet",
				Name:        "Greeting",
				Description: "Greet the user",
				Tags:        []string{"demo", "greeting"},
			},
		},
	}

	// Create A2A handler and server
	handler := a2a.NewDefaultAgentHandler(card, agent, cfg)
	server := a2a.NewServer(handler)

	log.Printf("A2A server starting on :%s", port)
	log.Printf("Agent Card: http://localhost:%s/.well-known/agent-card.json", port)

	return server.ListenAndServe(":" + port)
}

Terminal UI

go run ./example/tui-demo
go run ./example/tui-demo2
go run ./example/tui-demo3

Run one demo at a time in an interactive terminal. The TUI is layered around terminal I/O, themes, components, chat state, and an agent adapter. It is not a browser UI. Refer to each demo source for its configuration and behavior.

Additional Complete Examples

Command	What it demonstrates	Credentials
go run ./example/recovery	Interrupt, checkpoint, restore, resume	None
go run ./example/orchestration	Typed graph, pipeline/router, stream aggregation	None
go run ./example/http-server	Authenticated local HTTP chat with persisted threads	Provider key/model and local API token

See recovery, graphs, and HTTP API for full source and expected behavior.

Compatibility Suites

example/provider-compat contains provider compatibility tests, and example/itk implements an A2A integration test-kit agent. These are validation tools rather than recommended first examples.