Быстрый старт

Исходные файлы

Эта страница сгенерирована на основе следующих исходных файлов:

• examples/quickstart/main.go
• go.mod
• examples/README.md
• examples/a2a/main.go
• examples/mcp/main.go
• examples/web/main.go
• examples/rest/main.go
• examples/telemetry/main.go
• examples/vertexai/agent.go
• cmd/internal/adkcli/main.go

ADK Go (Agent Development Kit for Go) — это фреймворк для создания интеллектуальных агентов на языке Go. Проект предоставляет инструменты для быстрой разработки агентов с поддержкой различных моделей машинного обучения, протоколов взаимодействия и режимов развертывания.

Введение в ADK Go

Репозиторий ADK Go содержит модульные примеры для тестирования различных функций фреймворка. Примеры минималистичны и предназначены для проверки конкретных сценариев использования (examples/README.md:1-6). Эти примеры отличаются от репозитория google/adk-samples, который содержит более сложные end-to-end примеры для производственного использования.

Проект использует Go 1.25.0 и включает ключевые зависимости: Google GenAI SDK, Model Context Protocol (MCP) SDK, A2A Go для межагентного взаимодействия, а также инструменты телеметрии на базе OpenTelemetry (go.mod:1-5).

Требования к окружению

Системные требования

Переменные окружения

Для работы примеров необходимо установить переменную окружения GOOGLE_API_KEY. Примеры используют её для аутентификации при создании модели Gemini (examples/quickstart/main.go:37-39):

bash
1export GOOGLE_API_KEY="ваш-api-ключ"

Для интеграции с GitHub MCP сервером требуется дополнительный токен (examples/mcp/main.go:79-81):

bash
1export GITHUB_PAT="ваш-github-personal-access-token"

Установка

Клонирование репозитория

bash
1git clone https://github.com/google/adk-go.git
2cd adk-go

Установка зависимостей

bash
1go mod download

Модуль определён как google.golang.org/adk и использует стандартную систему зависимостей Go (go.mod:1).

Создание базового агента

Инициализация модели Gemini

Базовый агент создаётся с использованием модели Gemini 2.5 Flash. Модель инициализируется с конфигурацией клиента, содержащей API ключ (examples/quickstart/main.go:37-42):

go
1model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
2    APIKey: os.Getenv("GOOGLE_API_KEY"),
3})
4if err != nil {
5    log.Fatalf("Failed to create model: %v", err)
6}

Конфигурация LLMAgent

Агент создаётся через llmagent.New() с указанием имени, модели, описания, инструкций и инструментов (examples/quickstart/main.go:44-55):

go
1a, err := llmagent.New(llmagent.Config{
2    Name:        "weather_time_agent",
3    Model:       model,
4    Description: "Agent to answer questions about the time and weather in a city.",
5    Instruction: "Your SOLE purpose is to answer questions about the current time and weather in a specific city. You MUST refuse to answer any questions unrelated to time or weather.",
6    Tools: []tool.Tool{
7        geminitool.GoogleSearch{},
8    },
9})

Альтернативный пример создания погодного агента демонстрирует аналогичный подход с упрощёнными инструкциями (examples/a2a/main.go:44-63).

Запуск и развертывание

Использование Launcher

ADK Go использует систему Launcher для гибкого выбора режима запуска. Полный Launcher (full.NewLauncher()) включает все основные способы запуска (examples/README.md:19-23):

• console — интерактивная консоль
• restapi — REST API сервер
• a2a — Agent-To-Agent протокол
• webui — веб-интерфейс (может работать standalone или с restapi/a2a)

Код запуска агента

Типичный паттерн запуска выглядит следующим образом (examples/quickstart/main.go:57-65):

go
1config := &launcher.Config{
2    AgentLoader: agent.NewSingleLoader(a),
3}
4
5l := full.NewLauncher()
6if err = l.Execute(ctx, config, os.Args[1:]); err != nil {
7    log.Fatalf("Run failed: %v\n\n%s", err, l.CommandLineSyntax())
8}

Получение справки

Для просмотра доступных опций запуска выполните (examples/README.md:25):

bash
1go run ./examples/quickstart/main.go help

Альтернативный Launcher

Для производственного окружения доступен prod.NewLauncher(), который включает только restapi и a2a launchers (examples/README.md:27). Это рекомендуется для развёртываний, не требующих консольного режима или веб-интерфейса.

Интеграция с MCP

In-memory MCP сервер

ADK Go поддерживает интеграцию с Model Context Protocol (MCP). In-memory транспорт создаётся парой связанных объектов (examples/mcp/main.go:64-76):

go
1func localMCPTransport(ctx context.Context) mcp.Transport {
2    clientTransport, serverTransport := mcp.NewInMemoryTransports()
3    
4    server := mcp.NewServer(&mcp.Implementation{Name: "weather_server", Version: "v1.0.0"}, nil)
5    mcp.AddTool(server, &mcp.Tool{Name: "get_weather", Description: "returns weather in the given city"}, GetWeather)
6    _, err := server.Connect(ctx, serverTransport, nil)
7    if err != nil {
8        log.Fatal(err)
9    }
10    
11    return clientTransport
12}

Интеграция MCP toolset с агентом

MCP toolset подключается к агенту через поле Toolsets в конфигурации (examples/mcp/main.go:107-126):

go
1mcpToolSet, err := mcptoolset.New(mcptoolset.Config{
2    Transport: transport,
3})
4
5a, err := llmagent.New(llmagent.Config{
6    Name:        "helper_agent",
7    Model:       model,
8    Description: "Helper agent.",
9    Instruction: "You are a helpful assistant that helps users with various tasks.",
10    Toolsets: []tool.Toolset{
11        mcpToolSet,
12    },
13})

Удалённый MCP сервер

Для подключения к GitHub MCP серверу используется StreamableClientTransport с OAuth2 аутентификацией (examples/mcp/main.go:78-86). Выбор между локальным и удалённым режимом определяется переменной окружения AGENT_MODE (examples/mcp/main.go:100-105).

Расширенные возможности

A2A протокол

Agent-To-Agent (A2A) протокол обеспечивает взаимодействие между агентами. Сервер A2A запускается на динамическом порту с созданием AgentCard (examples/a2a/main.go:65-108):

go
1func startWeatherAgentServer() string {
2    listener, err := net.Listen("tcp", "127.0.0.1:0")
3    // ...
4    agentCard := &a2a.AgentCard{
5        Name:               agent.Name(),
6        Skills:             adka2a.BuildAgentSkills(agent),
7        PreferredTransport: a2a.TransportProtocolJSONRPC,
8        URL:                baseURL.JoinPath(agentPath).String(),
9        Capabilities:       a2a.AgentCapabilities{Streaming: true},
10    }
11    // ...
12}

Удалённый агент подключается через remoteagent.NewA2A с указанием источника AgentCard (examples/a2a/main.go:115-121).

Работа с артефактами

Пример web демонстрирует использование callback-функций для сохранения артефактов. Callback получает LLM response и сохраняет части контента через механизм артефактов (examples/web/main.go:39-49):

go
1func saveReportfunc(ctx agent.CallbackContext, llmResponse *model.LLMResponse, llmResponseError error) (*model.LLMResponse, error) {
2    if llmResponse == nil || llmResponse.Content == nil || llmResponseError != nil {
3        return llmResponse, llmResponseError
4    }
5    for _, part := range llmResponse.Content.Parts {
6        _, err := ctx.Artifacts().Save(ctx, uuid.NewString(), part)
7        if err != nil {
8            return nil, err
9        }
10    }
11    return llmResponse, llmResponseError
12}

Быстрый запуск

Минимальный путь к запуску

bash
1# 1. Установить API ключ
2export GOOGLE_API_KEY="ваш-ключ"
3
4# 2. Запустить quickstart пример
5go run ./examples/quickstart/main.go

Архитектура запуска

正在加载图表渲染器...

Проверка работоспособности

Ожидаемое поведение

При успешном запуске quickstart примера агент готов к обработке запросов о погоде и времени в городах. Инструкции агента явно ограничивают его функциональность вопросами о времени и погоде (examples/quickstart/main.go:48).

Проверка A2A сервера

При запуске A2A примера в логах появляется сообщение о старте сервера (examples/a2a/main.go:74):

Starting A2A server on http://127.0.0.1:xxxx

Частые проблемы и решения

Проблема 1: Отсутствует GOOGLE_API_KEY

Симптом: Ошибка "Failed to create model" при запуске.

Решение: Убедитесь, что переменная окружения установлена (examples/quickstart/main.go:38):

bash
1export GOOGLE_API_KEY="ваш-api-ключ"

Проблема 2: Некорректный режим AGENT_MODE

Симптом: MCP пример не подключается к ожидаемому серверу.

Решение: Проверьте значение переменной AGENT_MODE. Для локального режима не устанавливайте её или используйте "local", для GitHub — "github" (examples/mcp/main.go:100-105).

Проблема 3: Ошибка создания агента

Симптом: "Failed to create agent" в логах.

Решение: Проверьте корректность конфигурации llmagent.Config. Убедитесь, что модель инициализирована успешно и инструменты совместимы (examples/quickstart/main.go:53-55).

Проблема 4: Порт занят для A2A сервера

Симптом: "Failed to bind to a port" при запуске A2A примера.

Решение: A2A сервер использует динамическое назначение порта через net.Listen("tcp", "127.0.0.1:0") (examples/a2a/main.go:67). Если проблема сохраняется, проверьте доступность loopback интерфейса.

Следующие шаги

После успешного запуска quickstart примера рекомендуется:

1. Изучить примеры интеграции: MCP пример демонстрирует подключение внешних инструментов (examples/mcp/main.go:1-135)

2. Освоить A2A протокол: Пример a2a показывает межагентное взаимодействие (examples/a2a/main.go:1-131)

3. Изучить веб-интерфейс: Пример web демонстрирует работу с артефактами и сессиями (examples/web/main.go:1-116)

4. Продукционное развёртывание: Перейдите на prod.NewLauncher() для REST API и A2A режимов (examples/README.md:27)