Google ADK
Uma aplicação de agentes precisa de mais que uma definição de modelo. Ela recebe uma mensagem, identifica usuário e sessão, executa ferramentas, produz eventos e guarda mudanças que deverão estar disponíveis no próximo turno. O Google Agent Development Kit organiza esses elementos em agentes e serviços de runtime. Nosso caso será um assistente de viagens que reúne preferência de orçamento e proposta de roteiro, preservando o estado necessário para uma revisão posterior.
A aula distingue agent, session, state e runtime e mostra como padrões com vários agentes se conectam à implantação e à integração A2A. O código usa JavaScript local para visualizar eventos e escopos; não importa ADK nem chama Gemini. No laboratório, a integração real exige versão fixada e métodos verificados na documentação oficial. Esse cuidado evita transformar uma comparação de arquitetura em uma receita que parece executável, mas depende de APIs presumidas.
JavaScriptGoogle ADKAPIsAgentesAo terminar esta aula
- Sessão, estado e runtime possuem responsabilidades diferentes.
- Escopo de estado deve acompanhar o significado e a duração do dado.
- Agentes remotos exigem contrato, identidade e compatibilidade além da lógica local.
Antes de continuar: Laboratório: OpenAI Agents SDK
Agentes escolhem; ferramentas executam
AgentesUm agente orientado por LLM interpreta instruções e decide como responder ou usar ferramentas. Sua definição inclui identidade, instruções e ferramentas, enquanto o runtime conduz a invocação. Para viagens, uma ferramenta de consulta de horários não precisa ser um agente: recebe parâmetros e devolve dados. Um especialista de roteiro é útil quando precisa combinar restrições e produzir uma proposta contextual. A ferramenta deve validar cidade, data e acesso antes de consultar o serviço. A instrução do agente não substitui essa validação nem impede, sozinha, uma chamada malformada.
Em uma aplicação com vários agentes, descreva o papel de cada um pelo resultado que ele deve produzir. O especialista de transporte devolve alternativas com origem e validade; o especialista de roteiro combina somente alternativas verificadas. Uma descrição vaga como “agente inteligente de viagens” torna o roteamento difícil de avaliar. Também não forneça a cada especialista todas as credenciais do projeto. Um especialista que apenas organiza atividades não precisa reservar passagens. Separar consulta de reserva mantém a fronteira de efeito explícita e permite uma revisão humana antes de qualquer compromisso.
↗ Building Collaborative AI: A Developer's Guide to Multi-Agent Systems with ADK
Sessão contém eventos; estado guarda valores úteis
FundamentosUma sessão identifica uma interação e organiza seu histórico de eventos. O estado é um conjunto de valores usados durante essa interação, como orçamento, destino e restrições. A documentação do ADK descreve escopos de estado; valores de sessão, usuário, aplicação e invocação temporária têm durações e abrangências diferentes. Essa abrangência precisa corresponder ao significado do dado. Um orçamento desta viagem não deve se transformar acidentalmente em orçamento permanente do usuário, e uma variável temporária de cálculo não precisa ser conservada em todas as sessões.
↗ Session: Tracking individual conversations↗ State: The Session's Scratchpad
A atualização deve passar pelos mecanismos de eventos e serviços previstos no runtime utilizado, para que a persistência acompanhe o fluxo. Mudar um objeto em memória sem compreender quando o serviço registra a alteração pode produzir uma sessão que parece correta durante a execução e perde os dados no próximo turno. No simulador, aplicarEvento é o único caminho de escrita e acrescenta o evento ao histórico. Isso não reproduz a API do ADK; torna visível a relação entre uma observação, o delta de estado e a informação recuperável.
Runtime e padrões de colaboração
FundamentosO runtime coordena invocação, contexto e serviços que a aplicação configura. Serviços em memória são adequados a exercícios, mas não demonstram recuperação após reinício. Na implantação, escolha onde vivem sessões, artefatos e credenciais e como são isolados por usuário. Uma instância que reinicia não pode depender de um objeto local para conservar a aprovação de reserva. Também estabeleça prazo total e tratamento de falhas dos serviços. Uma ferramenta que demora indefinidamente impede o progresso mesmo que o agente saiba o que fazer em seguida.
Padrões sequenciais fazem uma etapa consumir a saída da anterior; padrões paralelos permitem consultas independentes; loops executam revisões com condição de parada. A escolha é uma decisão sobre dependências. Consultar atrações e transporte pode ocorrer em paralelo depois de conhecer destino e data. Construir o roteiro final depende das duas respostas. O estado compartilhado precisa de chaves ou regras de combinação que evitem que dois especialistas sobrescrevam o mesmo campo. Guardar ambos como “resultado” torna a ordem de conclusão responsável por qual evidência sobrevive.
↗ Building Collaborative AI: A Developer's Guide to Multi-Agent Systems with ADK↗ State: The Session's Scratchpad
const sessoes=new Map([['S1',{usuario:'ana',estado:{},eventos:[]}]]);
function aplicarEvento(id,usuario,evento) {
const s=sessoes.get(id);
if (!s || s.usuario!==usuario) throw new Error('sessao nao autorizada');
s.estado={...s.estado,...evento.delta}; s.eventos.push(evento);
return JSON.parse(JSON.stringify(s));
}
console.log(aplicarEvento('S1','ana',{tipo:'preferencia',delta:{orcamento:800}}));
console.log(aplicarEvento('S1','ana',{tipo:'proposta',delta:{roteiro:'duas atividades locais'}}));
try { aplicarEvento('S1','bia',{tipo:'leitura',delta:{}}); } catch(e) { console.log(e.message); }A2A e implantação ampliam a fronteira
APIsA integração A2A permite consumir um agente remoto com um contrato público de capacidades e operações, em vez de importar seu código. Isso acrescenta rede, autenticação e compatibilidade de protocolo ao problema. A existência de uma Agent Card não prova que o serviço é confiável ou que o usuário pode acessá-lo. Verifique origem, versão e capacidades, limite os dados enviados e trate falha remota como uma condição operacional. Não suponha que o estado interno de uma sessão local será transmitido integralmente; o contrato deve indicar o contexto mínimo necessário.
↗ A2A Quickstart: Consuming↗ Agent2Agent Protocol Specification v1.0.1
Implantar o assistente significa escolher processo de execução, armazenamento e observabilidade, além de disponibilizar um endpoint. Documente identidade do usuário, criação de sessão, acesso às ferramentas, retenção e tratamento de concorrência. No exemplo, dois turnos atualizam orçamento e proposta, e uma tentativa com outra identidade é recusada. Essa defesa torna visível uma regra que precisa continuar válida no servidor. Avalie duas sessões do mesmo usuário, usuários distintos e reinício: cada caso testa uma propriedade diferente de isolamento ou durabilidade.
Exercício aplicado
Um usuário informa orçamento de 800 reais e pede roteiro. Preserve esse orçamento entre turnos, impeça leitura por outro usuário e prepare a conexão com um especialista remoto de transporte.
- Execute os eventos de preferência e proposta e confira o estado.
- Teste leitura por outra identidade e crie uma segunda sessão independente.
- Implemente o fluxo no ADK com versão e serviço de sessão registrados.
- Desenhe a dependência A2A com versão compatível, timeout e dados mínimos.
Abrir resolução comentada
O evento preferencia guarda orçamento no estado de uma sessão de ana; o evento proposta adiciona o roteiro e preserva o evento anterior. A tentativa de leitura por bia é recusada. Esse comportamento demonstra isolamento de identidade no simulador, mas o identificador passado como argumento ainda é uma representação local. No servidor real, a identidade deve vir do mecanismo de autenticação, não de um campo livre da mensagem.
A integração ADK deve preservar o mesmo fluxo com seu serviço de sessão configurado. Quando mudar de memória para armazenamento persistente, execute um reinício entre os turnos e compare a leitura. Registre a versão e os escopos realmente utilizados. A aula não promete que implantar em determinada plataforma resolverá essas decisões automaticamente.
const sessoes=new Map([['S1',{usuario:'ana',estado:{},eventos:[]}]]);
function aplicarEvento(id,usuario,evento) {
const s=sessoes.get(id);
if (!s || s.usuario!==usuario) throw new Error('sessao nao autorizada');
s.estado={...s.estado,...evento.delta}; s.eventos.push(evento);
return JSON.parse(JSON.stringify(s));
}
console.log(aplicarEvento('S1','ana',{tipo:'preferencia',delta:{orcamento:800}}));
console.log(aplicarEvento('S1','ana',{tipo:'proposta',delta:{roteiro:'duas atividades locais'}}));
try { aplicarEvento('S1','bia',{tipo:'leitura',delta:{}}); } catch(e) { console.log(e.message); }Como conferir seu resultado
- O orçamento persiste entre os dois turnos da mesma sessão.
- Outra identidade não recebe o estado.
- A evidência ADK contém eventos e configuração do armazenamento.
Aplique em um problema novo
Primeiro resolva sem consultar a resposta. Explique suas decisões e guarde a evidência. A conclusão de leitura é independente desta autoavaliação.
Confira seus pré-requisitos
- Distinguir sessão/eventos/estado.
- Aplicar identidade de usuário.
Viagem orçamento 600 muda para 450 no segundo turno; usuário diferente pede mesma sessão. Desenhe ADK e fronteira remota.
Conferir raciocínio e critérios de domínio
O orçamento vigente é 450 após a correção, não 600; eventos e estado da sessão registram a mudança.
Outro userId não recebe dados da sessão. O especialista remoto só precisa destino/orçamento permitido, não todo histórico ou credenciais.
Runner executa a tool e conserva outputKey, mas InMemory Session Service perde estado em reinício. A decisão é não alegar continuidade durável dessa configuração.
Evidências para autoavaliação ou revisão por pares
- Continuidade: O orçamento vigente é 450 após a correção, não 600; eventos e estado da sessão registram a mudança.
- Isolamento: Outro userId não recebe dados da sessão. O especialista remoto só precisa destino/orçamento permitido, não todo histórico ou credenciais.
- Runtime: Runner executa a tool e conserva outputKey, mas InMemory Session Service perde estado em reinício. A decisão é não alegar continuidade durável dessa configuração.
Um erro frequente
Guardar sessão em memória prova durabilidade.
Armazenamento em memória não sobrevive ao reinício.
Teste sua compreensão
Responda com suas palavras antes de abrir o comentário. Saber explicar uma decisão é parte do domínio.
1. Uma ferramenta de transporte precisa ser agente?
Não. Uma operação determinística com contrato claro pode ser uma ferramenta.
Use um especialista quando há decisões contextuais que justificam seu custo.
2. Estado temporário é uma preferência permanente?
Não. O escopo deve seguir o significado do dado.
Guardar uma variável no escopo errado pode afetar outras viagens.
3. A Agent Card prova autorização?
Não. Descreve uma interface e capacidades.
A identidade e as permissões devem ser verificadas separadamente.
Seu progresso fica salvo neste navegador. Concluir a leitura não substitui demonstrar o domínio nos exercícios.
Referências e aprofundamento
Documentação oficial e trabalhos originais. As referências registram o escopo e as limitações para você conferir o que sustentam.
- Simple agents with LlmAgent
Google ADK • consulta: 2026-10-06
Google ADKAgentesIdentidade, instruções, tools, outputs e delegação do LlmAgent.
Limites: Cobertura varia por linguagem; comportamento do LLM é não determinístico.
- Session: Tracking individual conversations
Google ADK • consulta: 2026-10-06
Google ADKSession, eventos, IDs, estado e SessionService.
Limites: InMemorySessionService perde dados em reinícios; escolher serviço persistente para retomada.
- State: The Session's Scratchpad
Google ADK • consulta: 2026-10-06
Google ADKEstado serializável e escopos de sessão, user:, app: e temp:.
Limites: Persistência depende do serviço; diferenças de APIs por linguagem e limitações específicas de VertexAiSessionService.
- Agent Runtime
Google ADK • consulta: 2026-10-06
Google ADKAgentesadk web, run e api_server; referências de event loop, retomada e execução assíncrona.
Limites: Página organiza formas de execução; não é garantia de durabilidade de uma implantação.
- Building Collaborative AI: A Developer's Guide to Multi-Agent Systems with ADK
Google Cloud • consulta: 2026-10-06
AgentesIA & MLInfraestruturaHierarquia, agentes Sequential/Parallel/Loop, estado compartilhado e delegação.
Limites: Guia técnico oficial de 2025; validar sintaxe nas versões atuais, sem extrapolar promessas de ganho.
- A2A Quickstart: Consuming
Google ADK • consulta: 2026-10-06
Google ADKAPIsConsumir agente remoto A2A e uso de Agent Card; integração ADK.
Limites: A interoperabilidade depende da versão A2A e das capacidades concretas do SDK e servidor.
- Agent2Agent Protocol Specification v1.0.1
A2A Project / Linux Foundation • consulta: 2026-10-06
APIsAgent Cards, discovery, tarefas, mensagens, artefatos, interoperabilidade, segurança, comparação MCP e bindings JSON-RPC/gRPC/HTTP+JSON.
Limites: Fixar versão do protocolo/SDK no laboratório; JSON-RPC é um binding, não a única opção.
- Deployment
Google ADK • consulta: 2026-10-06
Google ADKAgent Runtime, Cloud Run, GKE e infraestrutura que executa containers.
Limites: Serviços gerenciados podem ter custo; comparar persistência e operação, sem assumir portabilidade de todas as APIs.