Google ADK – Criando seu Primeiro Agente de IA do Zero

Criar um agente de IA com o Google ADK é surpreendentemente simples quando você entende a anatomia do arquivo agent.py. O framework foi projetado para que desenvolvedores Python se sintam em casa desde o primeiro momento. Quatro parâmetros são suficientes para um agente funcional: name identifica o agente, model define qual LLM será usado, description resume o propósito e instruction estabelece o comportamento. Com esses elementos configurados corretamente, você tem um agente pronto para interagir. A execução pode acontecer de duas formas complementares. O comando adk web oferece interface visual para desenvolvimento e testes rápidos, permitindo conversar com o agente e inspecionar eventos em tempo real. Para integração em aplicações, o Runner executa o agente programaticamente, emitindo eventos assíncronos que você processa conforme necessário. Entender esse fluxo de eventos é fundamental para debugging e para construir experiências de usuário responsivas. Este artigo apresenta o caminho completo, do arquivo vazio até um agente funcional com capacidade de depuração.

Insights

• O nome da variável do agente em agent.py deve corresponder exatamente ao nome da pasta do agente, caso contrário o ADK não encontra o agente
• O parâmetro instruction é onde você define a personalidade e comportamento do agente, funcionando como um system prompt persistente
• Eventos são a unidade fundamental de comunicação no ADK, cada ação do agente gera eventos que podem ser inspecionados para debugging
• O Runner é o orquestrador central que conecta agente, sessão e modelo, gerenciando todo o ciclo de vida da execução
• O parâmetro description é usado por outros agentes em sistemas multi-agentes para decidir quando delegar tarefas

Próximos passos

Com seu primeiro agente funcionando, você está pronto para expandir suas capacidades. Nos próximos artigos:

Artigo 04: Modelos e Provedores Além do Gemini

• Usando OpenAI GPT-4 via LiteLLM
• Usando Claude via OpenRouter
• Modelos open source com Ollama

Artigo 05: Function Tools – Criando Ferramentas Customizadas

• Transformando funções Python em ferramentas
• Docstrings como documentação para o modelo
• Retornando dados estruturados

O código apresentado neste artigo é funcional. Clone, execute, experimente. Modifique as instruções, teste diferentes prompts, observe como os eventos mudam. A prática é o melhor professor.

FAQ

Por que meu agente não aparece na lista do adk web?

Verifique três coisas: (1) a pasta do agente contém agent.py e __init__.py, (2) o nome da variável no agent.py corresponde exatamente ao nome da pasta, (3) você está executando adk web da pasta pai correta (a pasta que contém a pasta do agente).

Qual a diferença entre instruction e description?

instruction define como o agente se comporta internamente, é o system prompt que guia todas as respostas. description é usado externamente por outros agentes para entender o que este agente faz e decidir quando delegar tarefas para ele.

Posso usar português nas instruções do agente?

Sim. Os modelos Gemini entendem português fluentemente. Você pode escrever instruções, descrições e interagir completamente em português. O agente responderá no idioma das instruções ou no idioma que o usuário usar.

O que acontece com a sessão quando o programa termina?

Com InMemorySessionService, todos os dados são perdidos quando o programa termina. Para persistência, use DatabaseSessionService com SQLite ou outro banco de dados. Isso será coberto em artigos futuros sobre estado e persistência.

Como faço para o agente responder de forma mais criativa ou mais precisa?

Use o parâmetro generate_content_config com temperature. Valores baixos (0.1-0.3) produzem respostas mais determinísticas e focadas. Valores altos (0.7-0.9) produzem respostas mais variadas e criativas. O padrão é geralmente em torno de 0.7.