Pack de démarrage d'agent avec l'ADK pour Go

1. Introduction

Bien que Python reste populaire pour l'entraînement et la recherche de modèles, les exigences pour l'inférence et l'orchestration des agents d'IA correspondent étroitement aux points forts de Go : faible latence, forte simultanéité et sécurité des types.

Passer d'un prototype à un agent de production pose des défis d'ingénierie que Go peut relever de manière exceptionnelle. Le typage statique de Go élimine les erreurs d'exécution lors de l'analyse des sorties LLM structurées. Ses goroutines légères, qui commencent avec seulement quelques kilo-octets de mémoire de pile par rapport aux plusieurs méga-octets des threads OS, permettent aux agents de gérer des milliers d'exécutions d'outils simultanées sans la surcharge d'une gestion de threads lourde.

Le Agent Development Kit (ADK) de Google comble le fossé entre ces avantages architecturaux et l'IA générative. Dans ce guide, vous allez créer un projet et le déployer en tant que microservice sécurisé sur Google Cloud.

Ce que vous allez devoir faire :

• Créer un projet d'agent prêt pour la production à l'aide de l'Agent Starter Pack
• Utilisez l'UI Web locale Agent Development Kit pour déboguer et tester votre agent.
• Développer et comprendre la logique de l'agent ADK basé sur Go
• Exécuter des tests unitaires et de bout en bout (E2E)
• Déployer l'agent de manière sécurisée sur Cloud Run

Ce dont vous avez besoin :

• Un navigateur Web (par exemple, Chrome)
• Un projet Google Cloud avec facturation activée

2. Avant de commencer

Créer un projet Google Cloud

Si vous n'en avez pas encore :

1. Dans la console Google Cloud, sur la page de sélection du projet, sélectionnez ou créez un projet Google Cloud.
2. Assurez-vous que la facturation est activée pour votre projet Cloud.

Démarrer Cloud Shell

Cloud Shell est un environnement de ligne de commande exécuté dans Google Cloud et fourni avec les outils nécessaires. Il servira d'environnement de développement principal pour cet atelier.

1. Cliquez sur Activer Cloud Shell en haut de la console Google Cloud.
2. Une fois connecté à Cloud Shell, exécutez la commande suivante pour vérifier votre authentification dans Cloud Shell :

gcloud auth list

3. Exécutez la commande suivante pour vérifier que votre projet est configuré pour être utilisé avec gcloud :

gcloud config get project

4. Vérifiez que le projet est conforme à vos attentes, puis exécutez la commande ci-dessous pour définir l'ID de votre projet :

export PROJECT_ID=$(gcloud config get project)

3. Premiers pas avec le pack de démarrage pour les agents

La bonne nouvelle, c'est que vous n'avez pas besoin de partir de zéro. Le pack de démarrage de l'agent est un outil CLI qui crée une structure de dossiers prête pour la production, y compris des pipelines CI/CD, une configuration d'infrastructure et du code récurrent.

Pour commencer, exécutez simplement la commande de création de build avec uvx :

uvx agent-starter-pack create

La CLI vous guidera tout au long d'une configuration interactive. Pour ce projet, sélectionnez les options suivantes :

• Nom du projet  : my-first-go-agent
• Modèle : option 6 (Go ADK, Go agent with A2A)
• CI/CD : option 3 (GitHub Actions)
• Région  : us-central1

L'outil s'authentifie automatiquement auprès de Google Cloud, active les API Vertex AI nécessaires et configure votre environnement local.

Lorsque le message vert Success! (Opération réussie !) s'affiche, vous pouvez continuer.

4. Visualiser l'agent en local

L'une des fonctionnalités les plus pratiques de l'ADK est la possibilité de déboguer visuellement votre agent avant de le déployer. En exécutant les commandes ci-dessous, vous lancez un serveur de développement local avec une interface utilisateur intégrée. Oui, il dispose d'une fenêtre de chat, mais il va bien au-delà en traçant les événements, les appels d'outils et plus encore.

Accédez au répertoire de votre projet et lancez le bac à sable :

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

Une fois le bac à sable en cours d'exécution, ouvrez l'aperçu Web dans Cloud Shell pour interagir avec l'agent que vous venez de créer.

L'agent est configuré avec un modèle ReAct (Reasoning and Acting), un framework qui est devenu fondamental dans l'IA agentive. La boucle continue de "Pensée ", "Action" et"Observation " du modèle ReAct améliore la résolution de problèmes et l'interprétabilité, ce qui rend le processus de prise de décision de l'agent transparent.

Par exemple, si vous demandez la météo, l'agent reconnaît l'intention, appelle l'outil get_weather et renvoie les données structurées.

5. Comprendre le code

Maintenant que nous avons vu l'agent en action, examinons le code Go qui le fait fonctionner. La logique se trouve dans agent/agent.go. Ce fichier gère les définitions d'outils, la configuration du modèle et l'initialisation.

L'ADK utilise des structs Go standards pour définir la façon dont le grand modèle de langage (LLM) interagit avec votre code. Pour définir les paramètres d'entrée de notre outil météo, nous définissons une structure avec des tags json et jsonschema :

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

GetWeatherResult définit la structure des données renvoyées à l'agent après l'exécution de l'outil :

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

GetWeather est une fonction Go standard qui accepte tool.Context et la structure d'arguments, exécute la logique métier et renvoie la structure de résultat :

// 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
}

La fonction NewRootAgent est chargée d'assembler et de renvoyer l'instance agent.Agent requise par le lanceur d'applications. Il commence par initialiser la configuration du modèle, en créant une instance de modèle gemini-2.5-flash soutenue par genai.BackendVertexAI.

Ensuite, il comble le fossé entre le code Go et le LLM en encapsulant la fonction GetWeather locale dans un functiontool. Cette étape enregistre l'outil sous le nom get_weather et fournit la description nécessaire au contexte du modèle. Enfin, il construit l'agent à l'aide de llmagent.New, qui combine le modèle Gemini initialisé, les instructions système qui définissent le comportement de l'agent et la tranche d'outils disponibles en une seule unité.

// 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. Tests

Le projet contient à la fois des tests unitaires pour la logique interne et des tests de bout en bout pour l'intégration du serveur.

Dans agent/agent_test.go, la fonction GetWeather est appelée avec une suite de scénarios de test pour vérifier que la chaîne de sortie correspond à ses attentes.

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)
			}
		})
	}
}

Les tests de bout en bout vérifient que l'agent fonctionne correctement lorsqu'il est exécuté en tant que serveur. Ils vérifient plus précisément que le protocole A2A ou Agent-to-Agent est pris en charge. Les tests de bout en bout démarrent une instance réelle du serveur, lui envoient des requêtes HTTP et vérifient les réponses.

Voici un extrait de 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")
    // ...
}

Vous pouvez exécuter tous les tests en local à l'aide du fichier makefile :

make test

7. Déploiement

Lorsque vous êtes prêt à partager votre agent avec le monde entier ou à le connecter à des écosystèmes de production, exécutez la commande de déploiement incluse :

make deploy

Cette commande crée automatiquement votre application à partir de la source à l'aide des packs de création Google Cloud, déclenchés par le flag --source .. Il déploie cette image sur Cloud Run avec plusieurs indicateurs optimisés pour la production : --memory "4Gi" pour fournir suffisamment de RAM pour les opérations LLM et --no-cpu-throttling pour s'assurer que le processeur reste alloué 24h/24 et 7j/7, ce qui peut éviter les démarrages à froid et garantir des réponses rapides lors des interactions avec l'agent.

Pour garantir l'exécution sécurisée de votre agent, le système est déployé avec une configuration stricte utilisant --no-allow-unauthenticated pour bloquer tout accès public par défaut, ce qui nécessite une authentification Identity and Access Management (IAM) pour toute requête. Il injecte également des variables d'environnement, y compris GOOGLE_GENAI_USE_VERTEXAI=True.

Comme votre application est sécurisée, vous devez activer Identity-Aware Proxy (IAP) pour y accéder de manière sécurisée via un navigateur. La documentation Cloud fournit des instructions détaillées dans Activer IAP pour Cloud Run.

Une fois les achats via l'application activés et votre adresse e-mail ajoutée en tant que principal, vous pouvez accéder à l'URL du service fournie après le déploiement. L'affichage de l'URL de base du service vous permet de voir la fiche de l'agent déployée. Cette structure JSON sert d'interface standard à votre agent, ce qui lui permet d'être découvert et utilisé de manière dynamique par d'autres agents, orchestrateurs ou interfaces utilisateur destinées aux utilisateurs.

8. Effectuer un nettoyage

Pour éviter que les ressources créées lors de cet atelier de programmation soient facturées en permanence sur votre compte Google Cloud, supprimez-les.

Vous pouvez supprimer votre projet Cloud, ce qui arrête la facturation de toutes les ressources utilisées dans ce projet :

gcloud projects delete $PROJECT_ID

Vous pouvez également supprimer le répertoire du projet de l'atelier de programmation du disque Cloud Shell :

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

9. Félicitations !

🎊 Mission accomplie ! Vous avez réussi à échafauder, tester et déployer un agent d'IA en Go à l'aide de l'Agent Development Kit.

Ce que vous avez accompli :

• Création d'une référence structurée initiale à l'aide du pack de démarrage de l'agent
• Vérifié et testé l'interface utilisateur et le code de l'agent localement
• Exploration des schémas typés et des fonctions mappant les comportements LLM aux objets Go
• Déployer le service Go sur Cloud Run

Étape suivante

• Documentation ADK : guides complets sur les modèles avancés, l'orchestration multi-agents et les systèmes de mémoire
• Pack de démarrage pour les agents : explorez des modèles, y compris des systèmes multi-agents et des architectures complexes.
• Documentation Cloud Run : informations détaillées sur l'optimisation des performances, les stratégies de scaling et les bonnes pratiques de sécurité
• Go Concurrency Patterns : comprendre les goroutines et les canaux vous aidera à créer des outils d'agent plus efficaces.
• Vertex AI Agent Engine : pour une infrastructure d'agent gérée avec orchestration et outils intégrés