Google ADK
Monte um assistente de viagens em dois turnos: primeiro registrar orçamento, depois produzir uma proposta compatível. Use o simulador para observar eventos e isolamento. A etapa ADK deve demonstrar uma ferramenta, uma sessão e uma mudança de estado no runtime instalado. Não será necessário reservar qualquer viagem ou usar dados pessoais reais.
A evidência principal é conseguir reconstruir o segundo turno a partir do estado correto, sem misturar usuários ou sessões. Você também vai desenhar onde entraria um agente A2A de transporte e quais falhas acrescentaria. Esse desenho precisa identificar contratos, dados enviados e timeout, em vez de representar comunicação remota como uma chamada local infalível.
BashGoogle ADKAPIsAgentesAo terminar esta aula
- Dois turnos precisam ler e escrever o estado da sessão correta.
- Memória local não prova recuperação após reinício.
- Paralelismo exige separar saídas e decidir como tratar contribuições ausentes.
Antes de continuar: Leitura: Google ADK
Construa o histórico antes de conectar um modelo
FundamentosSalve viagem.cjs e execute os dois eventos. Confira que orçamento permanece depois da proposta e que o histórico tem duas entradas. Troque o usuário na chamada de leitura e capture o erro. Agora crie outra sessão para ana com orçamento diferente. O primeiro orçamento não deve ser alterado quando você modificar a segunda sessão. Esse caso distingue dados próprios de uma viagem de uma preferência global. Se seu projeto precisar da preferência global, declare-a como tal e estabeleça quando pode ser atualizada.
Acrescente um campo de data à proposta e valide que o transporte consultado corresponde à mesma data. Esse controle impede combinar resultados de viagens diferentes que por acaso pertencem ao mesmo usuário. Antes de implementar especialistas, defina as chaves de saída: transporte_opcoes e roteiro_proposta, por exemplo. Faça cada produtor escrever apenas a sua chave, e a síntese final ler as duas. Você evita uma corrida simples em que o último especialista termina e apaga a contribuição anterior no campo resultado.
↗ Building Collaborative AI: A Developer's Guide to Multi-Agent Systems with ADK
Configure uma integração ADK reproduzível
FundamentosEscolha uma linguagem suportada pelo ADK, instale uma versão fixa e consulte os guias de agentes, sessões e runtime daquela instalação. Registre a configuração do serviço de sessão usado. Implemente um agente com uma ferramenta local que retorna opções de transporte fictícias, sem efetuar compra. Execute o primeiro turno para registrar orçamento e o segundo para solicitar um roteiro. Capture eventos e o estado após cada turno. Não reutilize a sintaxe do simulador como se fosse API do framework: ele mostra a semântica que você deve preservar.
↗ State: The Session's Scratchpad↗ Session: Tracking individual conversations
Se o serviço estiver em memória, reinicie a aplicação e registre que a sessão foi perdida. Se usar serviço persistente, repita o reinício e confira se os valores retornam. Apresente a evidência correspondente à configuração real. Para uma execução com modelo, registre qual ferramenta foi chamada e se a proposta respeitou o orçamento. Uma resposta com aparência de roteiro não demonstra uso de ferramenta. Compare o resultado com os dados fictícios retornados, incluindo preços e datas, para detectar informações inventadas.
Experimente colaboração e fronteira remota
FundamentosSepare transporte e atividades em duas contribuições independentes e justifique se podem ser paralelas. Acrescente uma síntese que só começa quando ambas estiverem disponíveis, ou que declara explicitamente uma contribuição ausente. Introduza um erro no transporte e observe como o roteiro comunica a lacuna. O padrão sequencial ou paralelo não decide, por si só, se a falha deve cancelar tudo ou permitir uma proposta parcial. Escreva essa política e teste a condição que a ativa.
↗ Building Collaborative AI: A Developer's Guide to Multi-Agent Systems with ADK
No desenho A2A, represente uma Agent Card verificada, uma requisição com destino e data e um resultado com identificador de tarefa. Determine prazo, autenticação e tratamento de estado pendente. Confira a versão de protocolo suportada pelo consumidor ADK e pelo agente remoto antes de implementar. A especificação A2A atual não autoriza presumir compatibilidade com exemplos de versões antigas. Se não houver serviço remoto configurado, identifique o desenho como preparação e não como uma integração já executada.
↗ A2A Quickstart: Consuming↗ State: The Session's Scratchpad
Planeje a implantação com evidência
FundamentosEscreva como o endpoint obtém identidade, como a sessão é selecionada e onde o estado permanece entre instâncias. Descreva também acesso a artefatos e segredos, sem incluir valores de credenciais no relatório. Para aceitar o laboratório, a execução local deve mostrar isolamento e a etapa integrada deve mostrar eventos de ADK. Os cenários ainda não executados, como múltiplos workers ou retomada A2A, ficam documentados como limites específicos, acompanhados do teste que seria necessário para verificá-los.
↗ A2A Quickstart: Consuming↗ State: The Session's Scratchpad
Resolução integrada, ambiente e evidência
FundamentosSalve como adk.mjs. A resolução usa LlmAgent, FunctionTool, Runner e InMemorySessionService reais de @google/adk2.2.0. A subclasse de BaseLlm é um dublê local: produz uma functionCall seguida de uma resposta e permite rodar o runtime sem Gemini. O Runner executa a tool, o Context.state registra transporte_destino e outputKey registra proposta; os dois turnos preservam orçamento 800 e produzem seis eventos. A consulta da mesma sessão com outro userId não retorna dados. Esses resultados foram executados localmente. InMemorySessionService perde estado após reinício e não é uma solução durável. Para uma execução com provedor, substitua new ModeloLocal() pelo identificador de modelo suportado e configure a autenticação oficial; essa variante ainda requer avaliação própria e não foi executada aqui.
↗ Simple agents with LlmAgent↗ State: The Session's Scratchpad↗ Session: Tracking individual conversations
npm init -y
npm install --save-exact @google/adk@2.2.0 zod@4.6.5
node adk.mjsExercí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
Salve como adk.mjs. A resolução usa LlmAgent, FunctionTool, Runner e InMemorySessionService reais de @google/adk2.2.0. A subclasse de BaseLlm é um dublê local: produz uma functionCall seguida de uma resposta e permite rodar o runtime sem Gemini. O Runner executa a tool, o Context.state registra transporte_destino e outputKey registra proposta; os dois turnos preservam orçamento 800 e produzem seis eventos. A consulta da mesma sessão com outro userId não retorna dados. Esses resultados foram executados localmente. InMemorySessionService perde estado após reinício e não é uma solução durável. Para uma execução com provedor, substitua new ModeloLocal() pelo identificador de modelo suportado e configure a autenticação oficial; essa variante ainda requer avaliação própria e não foi executada aqui.
O simulador atualiza somente a sessão existente quando a identidade corresponde ao proprietário. O estado final contém orçamento e proposta e o histórico contém dois eventos. A leitura com bia falha antes de devolver esses valores. Ao criar uma segunda sessão, use outro identificador e um objeto de estado independente; reaproveitar a mesma referência criaria um vazamento entre viagens.
No ADK, a resolução mantém a associação entre usuário, sessão e evento usando os serviços configurados, e demonstra a persistência por um reinício real quando houver armazenamento durável. O roteiro deve mencionar a origem local das opções. A2A entra como uma dependência remota com versão e autenticação verificadas, não como acesso irrestrito à sessão.
import { BaseLlm,LlmAgent,FunctionTool,Runner,InMemorySessionService } from '@google/adk';
import { z } from 'zod';
import assert from 'node:assert/strict';
class ModeloLocal extends BaseLlm {
constructor(){super({model:'curso-local'});this.passo=0;}
async *generateContentAsync(){
this.passo++;
yield {content:{role:'model',parts:this.passo===1?[{functionCall:{name:'opcoes_transporte',args:{destino:'Cuiaba'}}}]:[{text:'Roteiro ficticio com duas atividades locais.'}]},turnComplete:true};
}
async connect(){throw new Error('live nao usado');}
}
const tool=new FunctionTool({name:'opcoes_transporte',description:'Consulta opcoes ficticias, sem reservar.',parameters:z.object({destino:z.string()}).strict(),execute:({destino},ctx)=>{
if(ctx.userId!=='ana')throw new Error('usuario nao autorizado');
ctx.state.set('transporte_destino',destino);return {destino,preco:120};
}});
const service=new InMemorySessionService(),appName='viagens',userId='ana',sessionId='S1';
await service.createSession({appName,userId,sessionId,state:{orcamento:800}});
const agent=new LlmAgent({name:'roteiro',model:new ModeloLocal(),instruction:'Monte roteiro com orçamento {orcamento}.',tools:[tool],outputKey:'proposta'});
const runner=new Runner({agent,appName,sessionService:service});
async function turno(text){for await(const event of runner.runAsync({userId,sessionId,newMessage:{role:'user',parts:[{text}]}})){console.log('evento',event.author,event.content?.parts,event.actions?.stateDelta);}}
await turno('Quero roteiro para Cuiaba.');await turno('Mantenha o orçamento.');
const s=await service.getSession({appName,userId,sessionId});
assert.equal(s.state.orcamento,800);assert.equal(s.state.transporte_destino,'Cuiaba');assert(s.state.proposta);
assert.equal(await service.getSession({appName,userId:'bia',sessionId}),undefined);
console.log('estado',s.state,'eventos',s.events.length);
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.
No ADK, S9 de Ana começa 600 e recebe correção 450; S10 de Ana começa 300. Bia tenta ler S9. Dublê chama tool de transporte e devolve roteiro. Resolva estado e isolamento.
Conferir raciocínio e critérios de domínio
S9 termina com orçamento 450 e roteiro; S10 continua 300. Os objetos e eventos de uma sessão não modificam a outra.
Bia não recebe S9; conhecer sessionId não é autorização. A tool deve também verificar o contexto do usuário.
A sessão em memória não oferece recuperação após reinício. A2A remoto ainda não executado permanece projetado, não resultado observado.
Evidências para autoavaliação ou revisão por pares
- Estado por sessão: S9 termina com orçamento 450 e roteiro; S10 continua 300. Os objetos e eventos de uma sessão não modificam a outra.
- Autorização: Bia não recebe S9; conhecer sessionId não é autorização. A tool deve também verificar o contexto do usuário.
- Persistência e integração: A sessão em memória não oferece recuperação após reinício. A2A remoto ainda não executado permanece projetado, não resultado observado.
Um erro frequente
Mesmo usuário deve sempre compartilhar histórico entre viagens.
Sessões distintas não compartilham histórico automaticamente.
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.