Pacote inicial do agente com o ADK para Go

1. Introdução

ADK com Go

Embora o Python continue sendo uma linguagem popular para treinamento de modelos e pesquisa, os requisitos para veiculação e orquestração de agentes de IA se alinham muito com os pontos fortes do Go: baixa latência, alta simultaneidade e segurança de tipos.

A transição de um protótipo para um agente de produção apresenta desafios de engenharia que o Go pode lidar muito bem. A tipagem estática do Go elimina erros de tempo de execução ao analisar saídas estruturadas de LLM. As gorrotinas leves, que começam com apenas alguns kilobytes de memória de pilha em comparação com vários megabytes para linhas de execução do SO, permitem que os agentes processem milhares de execuções simultâneas de ferramentas sem a sobrecarga do gerenciamento pesado de linhas de execução.

O Kit de Desenvolvimento de Agentes (ADK) do Google faz a ponte entre essas vantagens arquitetônicas e a IA generativa. Neste guia, você vai criar um novo projeto e implantá-lo como um microsserviço seguro no Google Cloud.

Atividades deste laboratório:

  • Criar um projeto de agente pronto para produção usando o pacote inicial do agente
  • Use a interface da Web do Kit de Desenvolvimento de Agente local para depurar e testar seu agente
  • Desenvolver e entender a lógica do agente do ADK com base em Go
  • Executar testes de unidade e completos (E2E)
  • Implantar o agente com segurança no Cloud Run

Você vai precisar do seguinte:

  • Um navegador da web, como o Chrome
  • Tenha um projeto do Google Cloud com o faturamento ativado.

2. Antes de começar

Criar um projeto do Google Cloud

Se você ainda não tiver um:

  1. No console do Google Cloud, na página do seletor de projetos, selecione ou crie um projeto na nuvem do Google Cloud.
  2. Verifique se o faturamento está ativado para seu projeto do Cloud.

Iniciar o Cloud Shell

O Cloud Shell é um ambiente de linha de comando executado no Google Cloud que vem pré-carregado com as ferramentas necessárias. Ele será seu ambiente de desenvolvimento principal para este laboratório.

  1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.
  2. Depois de se conectar ao Cloud Shell, execute este comando para verificar sua autenticação no Cloud Shell:
gcloud auth list
  1. Execute o comando a seguir para confirmar se o projeto está configurado para uso com a gcloud:
gcloud config get project
  1. Confirme se o projeto está como esperado e execute o comando abaixo para definir o ID do projeto:
export PROJECT_ID=$(gcloud config get project)

3. Começar a usar o pacote inicial do agente

A boa notícia é que não é preciso começar do zero. O pacote inicial do agente é uma ferramenta de CLI que cria uma estrutura de pastas pronta para produção, incluindo pipelines de CI/CD, configuração de infraestrutura e código boilerplate.

Para começar, execute o comando de criação de build com uvx:

uvx agent-starter-pack create

A CLI vai orientar você em uma configuração interativa. Para este projeto, selecione as seguintes opções:

  • Nome do projeto: my-first-go-agent
  • Modelo:opção 6 (ADK do Go, agente do Go com A2A)
  • CI/CD:opção 3 (GitHub Actions)
  • Região : us-central1

Configuração do pacote básico do agente

Quando a mensagem verde Sucesso! aparecer, você poderá continuar.

Mensagem de sucesso

4. Como visualizar o agente localmente

Um dos recursos mais convenientes do ADK é a capacidade de depurar visualmente seu agente antes de implantá-lo. Ao executar os comandos abaixo, você inicia um servidor de desenvolvimento local com uma interface integrada. Sim, ele tem uma janela de chat, mas vai muito além disso, rastreando eventos, chamadas de ferramentas e muito mais.

Mude para o diretório do projeto e inicie o playground:

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

Quando o playground estiver em execução, abra a visualização da Web no Cloud Shell para interagir com o agente recém-criado.

O agente é configurado com um padrão ReAct (Reasoning and Acting), um framework que se tornou fundamental na IA agêntica. O loop contínuo de "Pensamento", "Ação" e "Observação" do padrão ReAct melhora a resolução de problemas e a interpretabilidade, tornando transparente o processo de tomada de decisão do Agente.

Por exemplo, se você perguntar sobre o clima, o agente vai reconhecer a intenção, invocar a ferramenta get_weather e retornar os dados estruturados.

Interface do Playground

5. Noções básicas sobre o código

Agora que vimos o agente em ação, vamos conferir o código Go que faz isso funcionar. A lógica está em agent/agent.go. Esse arquivo processa definições de ferramentas, configuração e inicialização de modelos.

O ADK usa structs Go padrão para definir como o modelo de linguagem grande (LLM) interage com seu código. Para definir os parâmetros de entrada da nossa ferramenta de clima, definimos uma struct com tags json e jsonschema:

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

GetWeatherResult define a estrutura dos dados retornados ao agente depois que a ferramenta é executada:

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

GetWeather é uma função padrão do Go que aceita tool.Context e a estrutura de argumentos, executando a lógica de negócios e retornando a estrutura 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
}

A função NewRootAgent é responsável por montar e retornar a instância agent.Agent necessária para o inicializador do aplicativo. Ele começa inicializando a configuração do modelo, criando uma instância de modelo gemini-2.5-flash com suporte de genai.BackendVertexAI.

Em seguida, ele preenche a lacuna entre o código Go e o LLM ao encapsular a função GetWeather local em um functiontool. Esta etapa registra a ferramenta com o nome get_weather e fornece a descrição necessária para o contexto do modelo. Por fim, ele cria o agente usando llmagent.New, que combina o modelo do Gemini inicializado, as instruções do sistema que definem o comportamento do agente e a parte das ferramentas disponíveis em uma única unidade.

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

O projeto contém testes de unidade para lógica interna e testes de ponta a ponta para integração do servidor.

Em agent/agent_test.go, a função GetWeather é chamada com um conjunto de casos de teste para verificar se a string de saída corresponde às 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)
			}
		})
	}
}

Os testes de ponta a ponta verificam se o agente funciona corretamente ao ser executado como um servidor, especificamente verificando se o suporte ao protocolo A2A ou agente para agente está funcionando corretamente. Os testes E2E iniciam uma instância real do servidor, enviando solicitações HTTP para ele e verificando as respostas.

Confira um snippet 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")
    // ...
}

É possível executar todos os testes localmente usando o makefile:

make test

7. Implantação

Quando estiver tudo pronto para compartilhar o agente com o mundo ou conectá-lo a ecossistemas de produção, execute o comando de implantação incluído:

make deploy

Esse comando cria automaticamente o aplicativo da origem usando os Buildpacks do Google Cloud, acionados pela flag --source .. Ele implanta essa imagem no Cloud Run com várias flags otimizadas para produção: --memory "4Gi" para fornecer RAM suficiente para operações de LLM e --no-cpu-throttling para garantir que a CPU permaneça alocada 24 horas por dia, 7 dias por semana, o que pode evitar inicializações a frio e garantir respostas rápidas nas interações do agente.

Para garantir que o agente seja executado com segurança, o sistema é implantado com uma configuração estrita usando --no-allow-unauthenticated para bloquear todo o acesso público por padrão, exigindo autenticação do Identity and Access Management (IAM) para qualquer solicitação. Ele também injeta variáveis de ambiente, incluindo GOOGLE_GENAI_USE_VERTEXAI=True.

URL do serviço de implantação

Ativar o IAP

Depois que a IAP for ativada e seu e-mail for adicionado como principal, navegue até o URL do serviço fornecido após a implantação. Ao visualizar o URL do serviço base, é possível ver o card do agente implantado. Essa estrutura JSON serve como a interface padrão do seu agente, permitindo que ele seja descoberto e consumido dinamicamente por outros agentes, orquestradores ou interfaces voltadas para humanos.

Card do agente

8. Limpeza

Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este codelab.

É possível excluir seu projeto na nuvem, o que interrompe o faturamento de todos os recursos usados nele:

gcloud projects delete $PROJECT_ID

Também é possível excluir o diretório do projeto do codelab do disco do Cloud Shell:

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

9. Parabéns!

🎊 Missão concluída! Você criou, testou e implantou um agente de IA em Go usando o Kit de Desenvolvimento de Agentes.

O que você fez:

  • Criou um valor de referência estruturado inicial usando o pacote inicial do agente
  • Verificou e testou a interface e o código do agente localmente
  • Investigou os esquemas tipados e as funções que mapeiam comportamentos de LLM para objetos Go
  • Implantou o serviço Go no Cloud Run

A seguir