Starter pack dell'agente con ADK per Go

1. Introduzione

Sebbene Python rimanga popolare per l'addestramento e la ricerca di modelli, i requisiti per il serving e l'orchestrazione degli agenti AI sono strettamente allineati ai punti di forza di Go: bassa latenza, concorrenza elevata e sicurezza dei tipi.

Il passaggio da un prototipo a un agente di produzione introduce sfide di ingegneria che Go può gestire in modo eccezionale. La tipizzazione statica di Go elimina gli errori di runtime durante l'analisi degli output strutturati degli LLM. Le sue goroutine leggere, che iniziano con pochi kilobyte di memoria dello stack rispetto a diversi megabyte per i thread del sistema operativo, consentono agli agenti di gestire migliaia di esecuzioni simultanee di strumenti senza l'overhead di una gestione complessa dei thread.

L'Agent Development Kit (ADK) di Google colma il divario tra questi vantaggi architetturali e l'AI generativa. In questa guida, creerai la struttura di un nuovo progetto ed eseguirai il deployment come microservizio sicuro su Google Cloud.

Operazioni da eseguire:

• Crea un progetto di agente pronto per la produzione utilizzando l'Agent Starter Pack
• Utilizza la UI web del kit di sviluppo di agenti locale per eseguire il debug e testare l'agente
• Sviluppare e comprendere la logica dell'agente ADK basata su Go
• Esegui test delle unità e end-to-end (E2E)
• Esegui il deployment dell'agente in modo sicuro in Cloud Run

Di che cosa hai bisogno:

• Un browser web come Chrome
• Un progetto Google Cloud con la fatturazione abilitata

2. Prima di iniziare

Crea un progetto Google Cloud

Se non ne hai già uno:

1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud.

Avvia Cloud Shell

Cloud Shell è un ambiente a riga di comando in esecuzione in Google Cloud che viene precaricato con gli strumenti necessari. che fungerà da ambiente di sviluppo principale per questo lab.

1. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
2. Una volta connesso a Cloud Shell, esegui questo comando per verificare l'autenticazione in Cloud Shell:

gcloud auth list

3. Esegui questo comando per verificare che il progetto sia configurato per l'utilizzo con gcloud:

gcloud config get project

4. Verifica che il progetto sia quello previsto, quindi esegui il comando riportato di seguito per impostare l'ID progetto:

export PROJECT_ID=$(gcloud config get project)

3. Inizia a utilizzare lo Starter Pack per gli agenti

La buona notizia è che non devi partire da zero. Agent Starter Pack è uno strumento CLI che crea una struttura di cartelle pronta per la produzione, incluse pipeline CI/CD, configurazione dell'infrastruttura e codice boilerplate.

Per iniziare, esegui il comando di creazione della build con uvx:

uvx agent-starter-pack create

La CLI ti guiderà in una configurazione interattiva. Per questo progetto, seleziona le seguenti opzioni:

• Nome progetto: my-first-go-agent
• Modello: opzione 6 (Go ADK, Go agent with A2A)
• CI/CD:opzione 3 (GitHub Actions)
• Regione: us-central1

Lo strumento esegue automaticamente l'autenticazione con Google Cloud, abilita le API Vertex AI necessarie e configura l'ambiente locale.

Quando viene visualizzato il messaggio verde Operazione riuscita., puoi procedere.

4. Visualizzare l'agente in locale

Una delle funzionalità più utili dell'ADK è la possibilità di eseguire il debug visivo dell'agente prima del deployment. Eseguendo i comandi riportati di seguito, avvii un server di sviluppo locale con un'interfaccia utente integrata. Sì, ha una finestra di chat, ma va ben oltre tracciando eventi, chiamate di strumenti e altro ancora.

Passa alla directory del progetto e avvia il playground:

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

Una volta eseguito il playground, apri l'anteprima web in Cloud Shell per interagire con l'agente appena creato.

L'agente è configurato con un pattern ReAct (Reasoning and Acting), un framework che è diventato fondamentale nell'AI agentica. Il ciclo continuo di "Pensiero ", "Azione" e"Osservazione " del pattern ReAct migliora la risoluzione dei problemi e l'interpretabilità, rendendo trasparente il processo decisionale dell'agente.

Ad esempio, se chiedi le previsioni del tempo, l'agente riconosce l'intento, richiama lo strumento get_weather e restituisce i dati strutturati.

5. Comprendere il codice

Ora che abbiamo visto l'agente in azione, diamo un'occhiata al codice Go che lo fa funzionare. La logica si trova in agent/agent.go. Questo file gestisce le definizioni degli strumenti, la configurazione e l'inizializzazione del modello.

L'ADK utilizza struct Go standard per definire il modo in cui il modello linguistico di grandi dimensioni (LLM) interagisce con il tuo codice. Per definire i parametri di input per il nostro strumento meteo, definiamo una struttura con i tag json e jsonschema:

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

GetWeatherResult definisce la struttura dei dati restituiti all'agente dopo l'esecuzione dello strumento:

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

GetWeather è una funzione Go standard che accetta tool.Context e la struct degli argomenti, esegue la logica di business e restituisce la struct dei risultati:

// 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 funzione NewRootAgent è responsabile dell'assemblaggio e della restituzione dell'istanza agent.Agent richiesta dal programma di avvio delle applicazioni. Inizia inizializzando la configurazione del modello, creando un'istanza del modello gemini-2.5-flash supportata da genai.BackendVertexAI.

Poi, colma il divario tra il codice Go e il LLM eseguendo il wrapping della funzione locale GetWeather in un functiontool. Questo passaggio registra lo strumento con il nome get_weather e fornisce la descrizione necessaria per il contesto del modello. Infine, crea l'agente utilizzando llmagent.New, che combina il modello Gemini inizializzato, le istruzioni di sistema che definiscono il comportamento dell'agente e la sezione degli strumenti disponibili in un'unica 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. Test

Il progetto contiene sia test unitari per la logica interna sia test end-to-end per l'integrazione del server.

In agent/agent_test.go, la funzione GetWeather viene chiamata con una serie di scenari di test per verificare che la stringa di output corrisponda alle aspettative.

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

I test end-to-end verificano che l'agente funzioni correttamente quando viene eseguito come server, controllando in particolare che il supporto del protocollo A2A o Agent-to-Agent funzioni correttamente. I test E2E avviano un'istanza reale del server, inviano richieste HTTP e controllano le risposte.

Ecco un estratto di 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")
    // ...
}

Puoi eseguire tutti i test in locale utilizzando il makefile:

make test

7. Deployment

Quando è tutto pronto per condividere l'agente con il mondo o per connetterlo agli ecosistemi di produzione, esegui il comando di deployment incluso:

make deploy

Questo comando crea automaticamente l'applicazione dall'origine utilizzando Google Cloud Buildpacks, attivato dal flag --source .. Esegue il deployment di questa immagine in Cloud Run con diversi flag ottimizzati per la produzione: --memory "4Gi" per fornire RAM sufficiente per le operazioni LLM e --no-cpu-throttling per garantire che la CPU rimanga allocata 24 ore al giorno, 7 giorni su 7, il che può impedire gli avvii a freddo e garantire risposte rapide nelle interazioni con l'agente.

Per garantire che l'agente venga eseguito in modo sicuro, il sistema viene implementato con una configurazione rigorosa che utilizza --no-allow-unauthenticated per bloccare tutto l'accesso pubblico per impostazione predefinita, richiedendo l'autenticazione Identity and Access Management (IAM) per qualsiasi richiesta. Inietta anche variabili di ambiente, tra cui GOOGLE_GENAI_USE_VERTEXAI=True.

Poiché la tua app è protetta, devi attivare Identity-Aware Proxy (IAP) per accedervi in modo sicuro tramite un browser. La documentazione di Cloud fornisce istruzioni passo passo in Abilitare IAP per Cloud Run.

Una volta abilitato IAP e aggiunta la tua email come entità, puoi passare all'URL del servizio fornito dopo il deployment. La visualizzazione dell'URL di base del servizio ti consente di vedere la scheda dell'agente di cui è stato eseguito il deployment. Questa struttura JSON funge da interfaccia standard dell'agente, consentendo di essere rilevata e utilizzata dinamicamente da altri agenti, orchestratori o interfacce utente rivolte agli utenti.

8. Esegui la pulizia

Per evitare che al tuo account Google Cloud vengano addebitati costi continui, elimina le risorse create durante questo Codelab.

Puoi eliminare il tuo progetto Cloud, interrompendo la fatturazione per tutte le risorse utilizzate al suo interno:

gcloud projects delete $PROJECT_ID

Potresti anche voler eliminare la directory del progetto codelab dal disco Cloud Shell:

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

9. Complimenti!

🎊 Missione completata. Hai creato, testato ed eseguito il deployment di un AI Agent in Go utilizzando l'Agent Development Kit.

Cosa hai ottenuto:

• È stata creata una baseline strutturata iniziale utilizzando lo starter pack dell'agente
• Verificato e testato l'interfaccia utente e il codice dell'agente in locale
• Ha esaminato il mapping di schemi e funzioni digitati dei comportamenti LLM agli oggetti Go
• Esegui il deployment del servizio Go su Cloud Run

Passaggi successivi

• Documentazione di ADK: guide complete su pattern avanzati, orchestrazione multi-agente e sistemi di memoria
• Agent Starter Pack: esplora i modelli, inclusi sistemi multi-agente e architetture complesse
• Documentazione di Cloud Run: analisi approfondite su ottimizzazione delle prestazioni, strategie di scalabilità e best practice per la sicurezza
• Go Concurrency Patterns: la comprensione delle goroutine e dei canali ti aiuterà a creare strumenti per agenti più efficienti
• Vertex AI Agent Engine: per un'infrastruttura di agenti gestita con orchestrazione e strumenti integrati