快速开始

本节运行一个简单的 Agent：模型调用 greet 工具，再根据工具结果回答用户。

前提条件

• Go 1.25 或更高版本。
• Chat Completions 兼容服务的 API 密钥。
• 账户可访问且支持工具调用的模型。

运行示例

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

其他兼容服务还需设置 OPENAI_BASE_URL，例如 https://api.deepseek.com/v1；使用 OpenAI 时可以不设置。请求使用你的服务账户，可能产生费用。

凭据安全

将密钥保存在本地环境或密钥管理服务中，不要提交到仓库或输入公开文档页面。

完整源码

以下是示例的完整源码。文档检查会编译这段程序，但不会调用外部模型服务。

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
}

执行过程

NewConfig 根据传入的选项创建配置。WithTools 注册工具的参数定义和执行函数，WithValidateArguments(true) 开启参数验证。Agent 将提示词和工具定义发送给模型；模型请求调用 greet 时，Agent 执行工具，再将结果发送给模型生成回答。

示例通过 context 将运行时间限制为两分钟，并设置五轮上限。运行结束后，Close 释放 Agent 资源。模型每次生成的回答可能不同，测试时不应要求回答与某个字符串完全一致。

在自己的项目中使用

在已有 Go 模块中安装依赖，并以上面的源码为起点：

go get github.com/covoyage/covonaut/agentcore

接下来阅读配置、工具与扩展和模型服务兼容性。