Quick Start

Run a small agent that calls a greet tool and returns a response.

Prerequisites

• Go 1.25 or later.
• An API key for a Chat Completions-compatible service.
• A model available to your account that supports tool calling.

Run the Example

From a checkout of the repository:

git clone https://github.com/covoyage/covonaut.git
cd covonaut
export OPENAI_API_KEY='your-api-key'
export AGENT_MODEL='your-tool-capable-model'
go run ./example/quickstart

For another compatible service, also set OPENAI_BASE_URL to its API base URL (for example, https://api.deepseek.com/v1). Leave it unset for OpenAI. The request uses your provider account and may incur charges.

Credentials

Keep keys in your local environment or secret manager. Never commit them or enter them into a public documentation page.

Complete Source

This is the same source compiled by the documentation checks.

package main

import (
	"context"
	"encoding/json"
	"errors"
	"fmt"
	"log"
	"os"
	"time"

	"github.com/covoyage/covonaut/agentcore"
	"github.com/covoyage/covonaut/provider/chatcompat"
)

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

func run() error {
	apiKey, model := os.Getenv("OPENAI_API_KEY"), os.Getenv("AGENT_MODEL")
	if apiKey == "" || model == "" {
		return errors.New("set OPENAI_API_KEY and AGENT_MODEL before running")
	}

	agent, err := agentcore.NewWithError(agentcore.NewConfig(
		agentcore.WithName("assistant"),
		agentcore.WithModel(model),
		agentcore.WithProvider(chatcompat.New(chatcompat.Config{
			APIKey:  apiKey,
			BaseURL: os.Getenv("OPENAI_BASE_URL"),
		})),
		agentcore.WithSystemPrompt("Use the greet tool when asked to greet someone."),
		agentcore.WithMaxTurns(5),
		agentcore.WithValidateArguments(true),
		agentcore.WithTools(&agentcore.Tool{
			Name:        "greet",
			Description: "Greet a person by name",
			Parameters: map[string]any{
				"type": "object",
				"properties": map[string]any{
					"name": map[string]any{"type": "string"},
				},
				"required": []string{"name"},
			},
			Func: func(ctx context.Context, args json.RawMessage) (any, error) {
				var input struct {
					Name string `json:"name"`
				}
				if err := json.Unmarshal(args, &input); err != nil {
					return nil, err
				}
				return "Hello, " + input.Name + "!", nil
			},
		}),
	))
	if err != nil {
		return err
	}
	defer agent.Close()

	ctx, cancel := context.WithTimeout(context.Background(), 2*time.Minute)
	defer cancel()
	output, err := agent.Run(ctx, "Greet Ada by name.")
	if err != nil {
		return err
	}
	fmt.Println(output)
	return nil
}

What Happens

NewConfig applies functional options. WithTools registers the tool's JSON Schema and implementation, and WithValidateArguments(true) enables argument validation. The provider receives the prompt and tool definition; if it requests greet, the agent executes it and sends the result back to the model.

The run has a two-minute context deadline and a five-turn limit. Close releases agent resources. Model behavior can vary, so the final response is not expected to match an exact string.

Use Your Own Project

In an existing Go module, install Covonaut and use the source above as a starting point:

go get github.com/covoyage/covonaut/agentcore

Next, learn configuration, tools and extensions, and provider compatibility.