É possível conectar agentes do Kit de Desenvolvimento de Agente (ADK) ao Cloud Storage para dar às cargas de trabalho de agentes acesso aos dados armazenados e aos conjuntos de ferramentas integrados do ADK. Essa integração permite persistir estado, memória e checkpoints para tarefas de longa duração, além de compartilhar arquivos intermediários em Agentic Workflows de vários agentes.
Para instruções de configuração e exemplos de código, consulte o guia de integração do ADK.
Benefícios da integração do Cloud Storage com o ADK
Ao integrar o Cloud Storage aos seus agentes, eles podem processar arquivos grandes, manter o histórico de conversas e reutilizar sua infraestrutura de armazenamento atual.
- Expansão de contexto dinâmica: dê aos agentes acesso a grandes conjuntos de dados, manuais ou arquivos de mídia sem atingir os limites de leitura simultânea de um LLM.
- Persistência durável de artefatos: armazene arquivos temporários, registros ou itens gerados (como relatórios ou imagens) de forma confiável fora do histórico de conversas.
- Suporte para qualquer tipo de artefato: processe e gere diferentes formatos, incluindo texto, imagens, áudio e vídeo, usando o Cloud Storage como armazenamento compartilhado.
- Controle de acesso refinado: controle o acesso do agente ao Cloud Storage usando papéis do IAM. O ADK usa a autenticação padrão do Google Cloud para garantir que os agentes tenham apenas as permissões mínimas necessárias para acessar dados ou realizar uma tarefa.
Casos de uso
Ao equipar seus agentes com os recursos do Cloud Storage, você pode atender aos seguintes casos de uso:
- Recuperação de contexto dinâmico, também conhecida como geração aumentada por recuperação (RAG)
- Persistência e arquivamento de artefatos
- Processamento de payloads grandes
- Gerenciamento automatizado de recursos
Recuperação de contexto dinâmico por RAG
Os agentes podem atuar como pesquisadores, descobrindo e lendo documentos no Cloud Storage para responder a perguntas em tempo real. Essa abordagem é útil para bases de conhecimento internas ou bots de suporte.
- Pesquisa de políticas: um agente pode listar e ler os manuais em PDF mais recentes em um bucket do
compliance-docspara responder às consultas dos usuários sobre a política da empresa. - Síntese de vários objetos: é possível criar um agente para recuperar e combinar informações de vários objetos de armazenamento para sintetizar um resumo unificado.
Persistência e arquivamento de artefatos
Salve grandes quantidades de dados gerados por agentes de forma confiável para revisão humana, outros sistemas ou auditoria.
- Relatórios automatizados: é possível criar um agente que analisa as métricas do banco de dados, gera um relatório resumido e o envia para um bucket do
reports-archive. - Armazenar mídia gerada: é possível configurar um sistema multiagente para salvar imagens ou objetos de áudio gerados no Cloud Storage e retornar apenas o URI de armazenamento ou um URL assinado.
Processamento de payloads grandes
Projete agentes para usar URIs de armazenamento (caminhos de arquivo) em vez de colar o conteúdo completo do arquivo no chat. Isso evita o alto custo e a ineficiência de enviar grandes CSVs ou bases de código para o LLM.
- Gerenciadores de pipeline de dados: é possível fazer com que o agente receba um URI de armazenamento em vez de consumir um CSV grande. O agente pode realizar análises processando blocos ou inspecionando metadados e retornar um painel de resumo.
- Fluxos de trabalho desacoplados: é possível projetar um agente para atuar como um supervisor que recebe um URI de armazenamento para um prefixo, uma pasta ou um bucket do Cloud Storage. O agente pode transmitir esse URI para workers de back-end para processar os objetos e gravar os resultados finais de volta no armazenamento. Esse padrão é compatível com serviços orientados a eventos, como o Cloud Run functions ou o Cloud Run, para processar dados de forma assíncrona.
Gerenciamento automatizado de recursos
Os agentes podem ajudar a otimizar o uso do armazenamento, automatizar tarefas administrativas e aplicar a governança em vários buckets. Isso é especialmente útil para equipes que gerenciam uma infraestrutura de armazenamento extensa.
- Auditoria de infraestrutura: é possível criar um agente para verificar as configurações do bucket (como local ou classe de armazenamento) e sugerir otimizações ou identificar configurações que não estão em conformidade.
- Limpeza de recursos: crie um agente para identificar buckets vazios ou desatualizados e automatizar o processo de limpeza com base nas suas políticas de retenção.
Conjuntos de ferramentas do ADK para o Cloud Storage
O ADK fornece os seguintes conjuntos de ferramentas em Python para o Cloud Storage. Entender as duas ajuda a definir os papéis dos agentes e restringir as permissões deles.
GCSToolset para gerenciamento de dados
O conjunto de ferramentas GCSToolset permite que o agente manipule arquivos em buckets atuais. Use-a para tarefas como ler documentos, fazer upload de resultados ou excluir objetos temporários.
- Ler objetos: recupere conteúdo diretamente usando
get_object_data. - Descobrir conteúdo: listar os objetos disponíveis usando
list_objects. - Inspecionar propriedades de objetos: verifique o tamanho do objeto ou os metadados
Content-Typeusandoget_object_metadata. - Fazer upload e persistir: crie novos objetos usando
create_object. - Remover objetos: remova objetos temporários usando
delete_objects.
GCSAdminToolset para infraestrutura
Use o conjunto de ferramentas GCSAdminToolset para gerenciar a infraestrutura de armazenamento, como criar buckets ou automatizar tarefas administrativas.
- Descobrir infraestrutura: listar buckets em um projeto usando
list_buckets. - Provisionar armazenamento: crie novos buckets usando
create_bucket. - Reconfigurar o armazenamento: modifique as configurações usando
update_bucket. - Desprovisionar armazenamento: remova buckets usando
delete_bucket. - Inspecionar o contexto do bucket: use
get_bucketpara acessar os metadados do bucket e verificar o local, a classe de armazenamento ou os controles de acesso.
Práticas recomendadas
Para otimizar o desempenho e a segurança do agente ao integrar com o Cloud Storage, considere as seguintes práticas recomendadas:
- Desvincule payloads grandes do histórico de conversas: evite transmitir arquivos grandes diretamente para o agente. Armazene-os no Cloud Storage e envie referências de arquivo (URIs). Isso reduz os custos de token e evita que os limites de contexto sejam atingidos.
- Aplique o princípio de privilégio mínimo: conceda ao agente apenas as permissões mínimas necessárias para realizar as tarefas. Evite papéis amplos, como
roles/storage.admin, a menos que esteja gerenciando a infraestrutura. Para operações de arquivo padrão, use papéis específicos, comoroles/storage.objectUserouroles/storage.objectViewer, restritos a buckets específicos. - Gerenciar configurações de forma centralizada: evite codificar nomes de buckets ou caminhos de nomes de objetos na lógica do agente. Use variáveis de ambiente ou gerenciadores de configuração para alternar entre ambientes de armazenamento de desenvolvimento, teste e produção.
- Implemente estratégias de recuperação eficientes: ao usar o Cloud Storage como uma camada para recuperação de conhecimento, não carregue documentos grandes inteiros no contexto do agente. Pré-processe e divida documentos em blocos ou use ferramentas de pesquisa dedicadas para recuperar apenas os segmentos relevantes.
Limitações
Ao integrar o Cloud Storage ao ADK, lembre-se das seguintes limitações:
- Objetos imutáveis: os objetos do Cloud Storage são imutáveis. Não é possível anexar dados a um objeto atual. Se o agente precisar registrar eventos continuamente em um único arquivo, ele precisará substituir o objeto completamente ou criar vários objetos pequenos e compor os objetos mais tarde.
- Latência no gerenciamento de estado de alta frequência: o Cloud Storage é adequado para armazenamento durável de artefatos e payloads grandes. No entanto, usar o Cloud Storage para atualizações de estado de alta frequência e baixa latência pode introduzir latência. Por exemplo, rastrear cada turno em uma conversa rápida pode ser mais lento do que usar caches em memória ou bancos de dados.
- Falta de atomicidade de vários objetos: as operações do Cloud Storage se aplicam a objetos individuais. Se o agente exigir atualizações atômicas em vários arquivos simultaneamente, implemente a lógica de coordenação no aplicativo.
A seguir
- Para conferir exemplos de código detalhados, instruções de configuração e referências de parâmetros para inicializar os conjuntos de ferramentas do Cloud Storage no seu aplicativo Python, consulte o guia de integração do ADK.
- Para usar habilidades de agente pré-criadas com seus agentes do ADK ou assistência de programação de IA, consulte Habilidades de agente do Cloud Storage.