Paquete de inicio de agente con el ADK para Go

1. Introducción

Si bien Python sigue siendo popular para el entrenamiento y la investigación de modelos, los requisitos para entregar y orquestar agentes de IA se alinean estrechamente con las fortalezas de Go: baja latencia, alta simultaneidad y seguridad de tipos.

La transición de un prototipo a un agente de producción presenta desafíos de ingeniería que Go puede abordar de manera excepcional. El lenguaje Go con escritura estática elimina los errores de tiempo de ejecución cuando se analizan los resultados estructurados de los LLM. Sus goroutines livianas, que comienzan con solo unos kilobytes de memoria de pila en comparación con varios megabytes para los subprocesos del SO, permiten que los agentes controlen miles de ejecuciones simultáneas de herramientas sin la sobrecarga de una administración pesada de subprocesos.

El Kit de desarrollo de agentes (ADK) de Google cierra la brecha entre estas ventajas arquitectónicas y la IA generativa. En esta guía, crearás un nuevo proyecto y lo implementarás como un microservicio seguro en Google Cloud.

Actividades:

• Crea un proyecto de agente listo para producción con el paquete inicial de agentes
• Utiliza la IU web local del Kit de desarrollo de agentes para depurar y probar tu agente
• Desarrollar y comprender la lógica del agente del ADK basada en Go
• Ejecuta pruebas de unidades y de extremo a extremo (E2E)
• Implementa el agente de forma segura en Cloud Run

Requisitos:

• Un navegador web, como Chrome
• Un proyecto de Google Cloud con la facturación habilitada.

2. Antes de comenzar

Crea un proyecto de Google Cloud

Si aún no tienes uno, haz lo siguiente:

1. En la página del selector de proyectos de la consola de Google Cloud, selecciona o crea un proyecto de Google Cloud.
2. Asegúrate de que la facturación esté habilitada para tu proyecto de Cloud.

Inicie Cloud Shell

Cloud Shell es un entorno de línea de comandos que se ejecuta en Google Cloud y que viene precargado con las herramientas necesarias. Funcionará como tu entorno de desarrollo principal para este lab.

1. Haz clic en Activar Cloud Shell en la parte superior de la consola de Google Cloud.
2. Una vez que te conectes a Cloud Shell, ejecuta este comando para verificar tu autenticación en Cloud Shell:

gcloud auth list

3. Ejecuta el siguiente comando para confirmar que tu proyecto esté configurado para usar gcloud:

gcloud config get project

4. Confirma que el proyecto sea el esperado y, luego, ejecuta el siguiente comando para configurar el ID del proyecto:

export PROJECT_ID=$(gcloud config get project)

3. Comienza a usar el paquete de inicio de agentes

La buena noticia es que no necesitas comenzar desde cero. El paquete de inicio del agente es una herramienta de CLI que genera una estructura de carpetas lista para la producción, incluidas las canalizaciones de CI/CD, la configuración de la infraestructura y el código estándar.

Para comenzar, simplemente ejecuta el comando de creación de compilación con uvx:

uvx agent-starter-pack create

La CLI te guiará a través de una configuración interactiva. Para este proyecto, selecciona las siguientes opciones:

• Nombre del proyecto: my-first-go-agent
• Plantilla: Opción 6 (ADK de Go, agente de Go con A2A)
• CI/CD: Opción 3 (acciones de GitHub)
• Región: us-central1

La herramienta se autentica automáticamente con Google Cloud, habilita las APIs de Vertex AI necesarias y configura tu entorno local.

Cuando veas el mensaje verde Success!, podrás continuar.

4. Visualiza el agente de forma local

Una de las funciones más convenientes del ADK es la capacidad de depurar visualmente tu agente antes de implementarlo. Si ejecutas los siguientes comandos, iniciarás un servidor de desarrollo local con una IU integrada. Sí, tiene una ventana de chat, pero va mucho más allá, ya que rastrea eventos, llamadas a herramientas y mucho más.

Cambia al directorio de tu proyecto y, luego, inicia el Playground:

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

Una vez que se ejecute la zona de pruebas, abre la vista previa web en Cloud Shell para interactuar con el agente que acabas de crear.

El agente se configura con un patrón ReAct (Reasoning and Acting), un framework que se convirtió en fundamental en la IA de agentes. El bucle continuo de "Pensamiento", "Acción" y "Observación" del patrón ReAct mejora la resolución de problemas y la interpretabilidad, lo que hace que el proceso de toma de decisiones del agente sea transparente.

Por ejemplo, si preguntas por el clima, el agente reconoce la intención, invoca la herramienta get_weather y devuelve los datos estructurados.

5. Comprende el código

Ahora que vimos el agente en acción, veamos el código de Go que lo hace funcionar. La lógica reside en agent/agent.go. Este archivo controla las definiciones de herramientas, la configuración del modelo y la inicialización.

El ADK usa structs estándar de Go para definir cómo el modelo de lenguaje grande (LLM) interactúa con tu código. Para definir los parámetros de entrada de nuestra herramienta del clima, definimos un struct con etiquetas json y jsonschema:

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

GetWeatherResult define la estructura de los datos que se devuelven al agente después de que se ejecuta la herramienta:

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

GetWeather es una función estándar de Go que acepta tool.Context y la estructura de argumentos, realiza la lógica empresarial y devuelve la estructura de resultados:

// 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 función NewRootAgent es responsable de ensamblar y devolver la instancia de agent.Agent que requiere el selector de aplicaciones. Comienza con la inicialización de la configuración del modelo, creando una instancia del modelo gemini-2.5-flash respaldada por genai.BackendVertexAI.

A continuación, une el código de Go y el LLM envolviendo la función GetWeather local en un functiontool. En este paso, se registra la herramienta con el nombre get_weather y se proporciona la descripción necesaria para el contexto del modelo. Por último, construye el agente con llmagent.New, que combina el modelo de Gemini inicializado, las instrucciones del sistema que definen el comportamiento del agente y la porción de herramientas disponibles en una sola unidad.

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

El proyecto contiene pruebas de unidades para la lógica interna y pruebas de extremo a extremo para la integración del servidor.

En agent/agent_test.go, se llama a la función GetWeather con un conjunto de casos de prueba para verificar que la cadena de salida coincida con sus expectativas.

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

Las pruebas de extremo a extremo verifican que el agente funcione correctamente cuando se ejecuta como servidor, y comprueban específicamente que la compatibilidad con el protocolo A2A o de agente a agente funcione correctamente. Las pruebas de E2E inician una instancia real del servidor, le envían solicitudes HTTP y verifican las respuestas.

Aquí tienes un fragmento 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")
    // ...
}

Puedes ejecutar todas las pruebas de forma local con el archivo makefile:

make test

7. Implementación

Cuando esté todo listo para compartir tu agente con el mundo o conectarlo a ecosistemas de producción, ejecuta el comando de implementación incluido:

make deploy

Este comando compila automáticamente tu aplicación desde el código fuente con los paquetes de compilación de Google Cloud, que se activan con la marca --source .. Implementa esta imagen en Cloud Run con varias marcas optimizadas para la producción: --memory "4Gi" para proporcionar suficiente RAM para las operaciones del LLM y --no-cpu-throttling para garantizar que la CPU permanezca asignada las 24 horas, todos los días, lo que puede evitar inicios en frío y garantizar respuestas rápidas en las interacciones del agente.

Para garantizar que tu agente se ejecute de forma segura, el sistema se implementa con una configuración estricta que usa --no-allow-unauthenticated para bloquear todo el acceso público de forma predeterminada, lo que requiere la autenticación de Identity and Access Management (IAM) para cualquier solicitud. También inserta variables de entorno, incluida GOOGLE_GENAI_USE_VERTEXAI=True.

Como tu app está protegida, deberás habilitar Identity-Aware Proxy (IAP) para acceder a ella de forma segura a través de un navegador. En la documentación de Cloud, se proporcionan instrucciones paso a paso en Habilita IAP para Cloud Run.

Una vez que se habilite la IAP y se agregue tu correo electrónico como principal, podrás navegar a la URL del servicio que se proporciona después de la implementación. Ver la URL base del servicio te permite ver la tarjeta del agente implementada. Esta estructura JSON sirve como interfaz estándar de tu agente, lo que permite que otros agentes, orquestadores o IU orientadas al usuario la descubran y consuman de forma dinámica.

8. Limpieza

Para evitar que se apliquen cargos a tu cuenta de Google Cloud, borra los recursos que creaste durante este Codelab.

Puedes borrar tu proyecto de Cloud, lo que detendrá la facturación de todos los recursos que se usen en él:

gcloud projects delete $PROJECT_ID

También puedes borrar el directorio del proyecto del codelab de tu disco de Cloud Shell:

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

9. ¡Felicitaciones!

🎊 ¡Misión cumplida! Creaste, probaste e implementaste correctamente un agente de IA en Go con el Kit de desarrollo de agentes.

Qué lograste:

• Se creó un modelo inicial estructurado básico con el paquete de inicio de Agent
• Verificamos y probamos la IU y el código del agente de forma local.
• Investigamos los esquemas escritos y las funciones que asignan los comportamientos del LLM a objetos de Go.
• Implementaste el servicio de Go en Cloud Run

Próximos pasos

• Documentación del ADK: Guías completas sobre patrones avanzados, organización de varios agentes y sistemas de memoria
• Agent Starter Pack: Explora plantillas, incluidos sistemas multiagente y arquitecturas complejas
• Documentación de Cloud Run: Análisis detallados sobre la optimización del rendimiento, las estrategias de escalamiento y las prácticas recomendadas de seguridad
• Patrones de simultaneidad de Go: Comprender las goroutines y los canales te ayudará a crear herramientas para agentes más eficientes
• Vertex AI Agent Engine: Para la infraestructura de agentes administrados con organización y herramientas integradas