Стартовый пакет агента с ADK для Go

1. Введение

Хотя Python по-прежнему популярен для обучения моделей и исследований, требования к запуску и управлению агентами ИИ тесно связаны с сильными сторонами Go: низкой задержкой, высокой параллельностью и типобезопасностью.

Переход от прототипа к производственному агенту создает инженерные проблемы, с которыми Go справляется исключительно хорошо. Статическая типизация Go исключает ошибки во время выполнения при разборе структурированных выходных данных LLM. Его легковесные горутины, которые начинают работу всего с нескольких килобайт памяти стека по сравнению с несколькими мегабайтами для потоков операционной системы, позволяют агентам обрабатывать тысячи одновременных запусков инструментов без накладных расходов на сложное управление потоками.

Комплект разработки агентов Google (ADK) устраняет разрыв между этими архитектурными преимуществами и генеративным искусственным интеллектом. В этом руководстве вы создадите новый проект и развернете его в качестве безопасного микросервиса в Google Cloud.

Что вы будете делать:

• Создайте готовый к внедрению проект агента, используя стартовый пакет Agent Starter Pack.
• Используйте локальный веб-интерфейс Agent Development Kit для отладки и тестирования вашего агента.
• Разрабатывать и понимать логику агента ADK на основе Go.
• Выполните модульные и сквозные (E2E) тесты.
• Разверните агент в Cloud Run безопасным способом.

Что вам понадобится:

• Веб-браузер, например Chrome.
• Проект Google Cloud с включенной функцией выставления счетов.

2. Прежде чем начать

Создайте проект в Google Cloud.

Если у вас его ещё нет:

1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud .
2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов.

Запустить Cloud Shell

Cloud Shell — это среда командной строки, работающая в Google Cloud и поставляемая с предустановленными необходимыми инструментами. Она будет служить вашей основной средой разработки для этой лабораторной работы.

1. В верхней части консоли Google Cloud нажмите кнопку «Активировать Cloud Shell» .
2. После подключения к Cloud Shell выполните следующую команду для проверки аутентификации в Cloud Shell:

gcloud auth list

3. Выполните следующую команду, чтобы убедиться, что ваш проект настроен для использования с gcloud:

gcloud config get project

4. Убедитесь, что проект соответствует ожиданиям, а затем выполните команду ниже, чтобы установить идентификатор проекта :

export PROJECT_ID=$(gcloud config get project)

3. Начните работу с пакетом инструментов для агентов.

Хорошая новость в том, что вам не нужно начинать с нуля. Agent Starter Pack — это инструмент командной строки, который создает готовую к использованию структуру папок, включая конвейеры CI/CD, конфигурацию инфраструктуры и шаблонный код.

Для начала просто выполните команду создания сборки с помощью uvx :

uvx agent-starter-pack create

Интерфейс командной строки проведет вас через интерактивную настройку. Для этого проекта выберите следующие параметры:

• Название проекта: my-first-go-agent
• Шаблон: Вариант 6 (Используйте ADK, используйте агента с A2A)
• CI/CD: Вариант 3 (GitHub Actions)
• Регион: us-central1

Этот инструмент автоматически проходит аутентификацию в Google Cloud, активирует необходимые API Vertex AI и настраивает вашу локальную среду.

Как только вы увидите зеленое сообщение « Успех! », вы можете продолжить.

4. Локальная визуализация агента.

Одна из самых удобных функций ADK — возможность визуальной отладки агента перед его развертыванием. Выполнив приведенные ниже команды, вы запустите локальный сервер разработки со встроенным пользовательским интерфейсом. Да, в нем есть окно чата, но он предлагает гораздо больше, отслеживая события, вызовы инструментов и многое другое.

Перейдите в каталог своего проекта и запустите песочницу:

cd my-first-go-agent
make install
make playground

После запуска тестовой среды откройте веб-версию предварительного просмотра в Cloud Shell, чтобы взаимодействовать с созданным агентом.

Агент настроен на основе паттерна ReAct (Рассуждение и Действие) — структуры, ставшей основополагающей в агентном ИИ. Непрерывный цикл паттерна ReAct, состоящий из «Мысли», «Действия» и «Наблюдения», повышает эффективность решения проблем и интерпретируемость, делая процесс принятия решений агентом прозрачным.

Например, если вы запрашиваете погоду, агент распознает намерение, вызывает инструмент get_weather и возвращает структурированные данные.

5. Понимание Кодекса

Теперь, когда мы увидели агента в действии, давайте рассмотрим код на Go, который обеспечивает его работу. Логика находится в agent/agent.go . Этот файл отвечает за определение инструментов, конфигурацию модели и инициализацию.

ADK использует стандартные структуры Go для определения того, как модель большого языка (LLM) взаимодействует с вашим кодом. Для определения входных параметров нашего инструмента прогноза погоды мы определяем структуру с тегами json и jsonschema :

type GetWeatherArgs struct {
    City string `json:"city" jsonschema:"City name to get weather for"`
}

GetWeatherResult определяет структуру данных, возвращаемых агенту после выполнения инструмента:

// GetWeatherResult defines the output for the get_weather tool.
type GetWeatherResult struct {
	Weather string `json:"weather"`
}

Функция GetWeather — это стандартная функция Go, которая принимает tool.Context и структуру аргументов, выполняет бизнес-логику и возвращает структуру результата:

// GetWeather returns mock weather data for a city.
func GetWeather(_ tool.Context, args GetWeatherArgs) (GetWeatherResult, error) {
	return GetWeatherResult{
		Weather: "It's sunny and 72°F in " + args.City,
	}, nil
}

Функция NewRootAgent отвечает за сборку и возврат экземпляра agent.Agent , необходимого для запуска приложения. Она начинает с инициализации конфигурации модели, создавая экземпляр модели gemini-2.5-flash поддерживаемый genai.BackendVertexAI .

Далее, он устраняет разрыв между кодом Go и LLM, оборачивая локальную функцию GetWeather в functiontool . На этом этапе инструмент регистрируется с именем get_weather и предоставляется необходимое описание контекста модели. Наконец, он создает агента с помощью llmagent.New , который объединяет инициализированную модель Gemini, системные инструкции, определяющие поведение агента, и набор доступных инструментов в единый блок.

// NewRootAgent creates and returns the root agent with all configured tools.
func NewRootAgent(ctx context.Context) (agent.Agent, error) {
	model, err := gemini.NewModel(ctx, "gemini-2.5-flash", &genai.ClientConfig{
		Backend: genai.BackendVertexAI,
	})

	weatherTool, err := functiontool.New(functiontool.Config{
		Name:        "get_weather",
		Description: "Get the current weather for a city.",
	}, GetWeather)

	rootAgent, err := llmagent.New(llmagent.Config{
		Name:        "my-first-go-agent",
		Model:       model,
		Description: "A helpful AI assistant.",
		Instruction: "You are a helpful AI assistant designed to provide accurate and useful information.",
		Tools:       []tool.Tool{weatherTool},
	})
	// ... (additional logic omitted for brevity)
	return rootAgent, nil
}

6. Тестирование

Проект включает в себя как модульные тесты для внутренней логики, так и сквозные тесты для интеграции с сервером.

В agent/agent_test.go функция GetWeather вызывается с набором тестовых случаев для проверки соответствия выходной строки ее ожиданиям.

func TestGetWeather(t *testing.T) {
	// tests struct initialized with "San Francisco" and "New York"

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			// Pass nil for tool.Context since GetWeather doesn't use it
			result, err := GetWeather(nil, GetWeatherArgs{City: tt.city})
			if err != nil {
				t.Fatalf("GetWeather() error = %v", err)
			}
			if !strings.Contains(result.Weather, tt.wantCity) {
				t.Errorf("GetWeather() = %v, want city %v in response", result.Weather, tt.wantCity)
			}
		})
	}
}

Сквозные тесты проверяют корректность работы агента при запуске в качестве сервера, в частности, проверяют правильность работы поддержки протоколов A2A или Agent-to-Agent. Сквозные тесты запускают реальный экземпляр сервера, отправляют ему HTTP-запросы и проверяют ответы.

Вот фрагмент кода из e2e/integration/server_e2e_test.go :

func TestA2AMessageSend(t *testing.T) {
    if testing.Short() { t.Skip("Skipping E2E test in short mode") }

    // Start server (local variable to avoid race conditions)
    t.Log("Starting server process")
    serverProcess := startServer(t)
    defer stopServer(t, serverProcess)

    if !waitForServer(t, 90*time.Second) {
	    t.Fatal("Server failed to start")
    }
    t.Log("Server process started")
    // ...
}

Все тесты можно запустить локально с помощью файла makefile:

make test

7. Развертывание

Когда вы будете готовы поделиться своим агентом со всем миром или подключить его к производственным экосистемам, выполните прилагаемую команду развертывания:

make deploy

Эта команда автоматически собирает ваше приложение из исходного кода с помощью Google Cloud Buildpacks , запускаемой флагом --source . . Она развертывает этот образ в Cloud Run с несколькими оптимизированными для производственной среды флагами: --memory "4Gi" для обеспечения достаточного объема оперативной памяти для операций LLM и --no-cpu-throttling для обеспечения круглосуточной работы ЦП, что может предотвратить холодные запуски и обеспечить быструю реакцию при взаимодействии с агентами.

Для обеспечения безопасной работы вашего агента система развертывается со строгой конфигурацией, использующей --no-allow-unauthenticated , который по умолчанию блокирует весь публичный доступ, требуя аутентификации через систему управления идентификацией и доступом (IAM) для любых запросов. Также внедряются переменные среды, включая GOOGLE_GENAI_USE_VERTEXAI=True .

Поскольку ваше приложение защищено, вам потребуется включить Identity-Aware Proxy (IAP), чтобы безопасно получить к нему доступ через браузер. В документации Cloud Run приведены пошаговые инструкции по включению IAP для Cloud Run .

После включения IAP и добавления вашего адреса электронной почты в качестве субъекта, вы можете перейти по URL-адресу службы, предоставленному после развертывания. Просмотр базового URL-адреса службы позволяет увидеть развернутую карточку агента . Эта структура JSON служит стандартным интерфейсом вашего агента, позволяя динамически обнаруживать и использовать его другими агентами, оркестраторами или пользовательскими интерфейсами.

8. Уборка

Чтобы избежать постоянных списаний средств с вашего аккаунта Google Cloud, удалите ресурсы, созданные в ходе этого практического занятия.

Вы можете удалить свой облачный проект, после чего прекратится выставление счетов за все используемые в нем ресурсы:

gcloud projects delete $PROJECT_ID

Также вы можете удалить каталог проекта codelab с диска Cloud Shell:

rm -rf ~/my-first-go-agent

9. Поздравляем!

🎊 Миссия выполнена! Вы успешно создали, протестировали и развернули ИИ-агента на языке Go, используя комплект разработки агентов (Agent Development Kit).

Чего вы достигли:

• Создана исходная структурированная базовая модель с использованием Agent Starter Pack.
• Проверил и протестировал пользовательский интерфейс агента и код локально.
• Углубился в типизированные схемы и функции, сопоставляющие поведение LLM с объектами Go.
• Развернул Go-сервис в Cloud Run.

Что дальше?

• Документация ADK : Полные руководства по продвинутым шаблонам, оркестровке многоагентных систем и системам памяти.
• Стартовый пакет для агентов : изучите шаблоны, включая многоагентные системы и сложные архитектуры.
• Документация Cloud Run : подробный анализ оптимизации производительности, стратегий масштабирования и лучших практик обеспечения безопасности.
• Шаблоны параллельного программирования в Go : понимание горутин и каналов поможет вам создавать более эффективные инструменты для агентов.
• Vertex AI Agent Engine : для управляемой агентской инфраструктуры со встроенной оркестрацией и инструментами.