É possível conectar os agentes do Kit de desenvolvimento de agentes (ADK, na sigla em inglês) ao Cloud Storage. Essa conexão permite que os agentes usem conjuntos de ferramentas integrados do ADK.
Como desenvolvedor de IA, você pode integrar o ADK ao Cloud Storage para conectar seus agentes aos dados armazenados. Essa integração ajuda a escalonar as cargas de trabalho dos agentes. É possível usar o Cloud Storage para manter o estado, a memória e os checkpoints de tarefas de longa duração. Também é possível usar o Cloud Storage para compartilhar arquivos intermediários em um fluxo de trabalho de vários agentes.
Este documento descreve os benefícios da integração do Cloud Storage com o ADK. Ele aborda casos de uso comuns e os recursos dos conjuntos de ferramentas disponíveis. Para instruções de configuração detalhadas 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 dinâmica do contexto: conceda aos agentes acesso a grandes conjuntos de dados, manuais ou arquivos de mídia sem atingir os limites de quanto um LLM pode ler de uma só vez.
- 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 a 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 detalhado: controle o acesso do agente ao Cloud Storage com precisão usando os papéis do IAM. O ADK usa a autenticação padrão Cloud de Confiance by S3NS 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 recursos do Cloud Storage, você pode resolver os seguintes casos de uso:
- Recuperação de contexto dinâmico, também conhecida como geração aumentada por recuperação (RAG, na sigla em inglês)
- Persistência e arquivamento de artefatos
- Processamento de payloads grandes
- Gerenciamento automatizado de recursos
Recuperação de contexto dinâmico usando a 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: você pode fazer com que um agente liste e leia os manuais em PDF mais recentes em um bucket
compliance-docspara responder a consultas do usuário sobre a política da empresa. - Síntese de vários objetos: você pode 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 pelo agente de forma confiável para revisão humana, outros sistemas ou auditoria.
- Relatórios automatizados: você pode criar um agente que analisa métricas de banco de dados, gera um relatório resumido e faz upload dele para um bucket
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
Crie agentes para usar URIs de armazenamento (caminhos de arquivos) em vez de colar o conteúdo completo do arquivo no chat. Isso evita o alto custo e a ineficiência de enviar CSVs ou bases de código grandes para o LLM.
- Processadores de pipeline de dados: você pode fazer com que o agente receba um URI de armazenamento em vez de consumir um CSV grande. Em seguida, o agente pode realizar a análise processando blocos ou inspecionando metadados e retornar um painel de resumo.
- Fluxos de trabalho desacoplados: você pode criar um agente para atuar como um supervisor que recebe um URI de armazenamento para um prefixo, pasta ou bucket do Cloud Storage. O agente pode transmitir esse URI aos 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 é particularmente útil para equipes que gerenciam uma infraestrutura de armazenamento extensa.
- Auditoria de infraestrutura: você pode criar um agente para verificar as configurações de bucket (como local ou classe de armazenamento) e sugerir otimizações ou identificar configurações não compatíveis.
- Limpeza de recursos: é possível criar um agente para identificar buckets vazios ou desatualizados e automatizar o processo de limpeza com base nas 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 os dois ajuda a definir os papéis do agente e restringir as permissões.
GCSToolset para gerenciamento de dados
O conjunto de ferramentas GCSToolset permite que o agente manipule arquivos em buckets atuais. Use-o para tarefas como ler documentos, fazer upload de resultados ou excluir objetos temporários.
- Ler objetos: recupere o conteúdo diretamente usando
get_object_data. - Descobrir conteúdo: liste os objetos disponíveis usando
list_objects. - Inspecionar propriedades do objeto: 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: liste buckets em um projeto usando
list_buckets. - Provisionar armazenamento: crie novos buckets usando
create_bucket. - Reconfigurar armazenamento: modifique as configurações usando
update_bucket. - Desprovisionar armazenamento: remova buckets usando
delete_bucket. - Inspecionar o contexto do bucket: receba metadados do bucket usando
get_bucketpara verificar o local, a classe de armazenamento ou os controles de acesso do bucket.
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:
- Desacople 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 arquivos (URIs) em vez disso. Isso reduz os custos de token e evita atingir os limites de contexto.
- 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 direcionados, 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.
- Implementar 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 ou use ferramentas de pesquisa dedicadas para recuperar apenas os segmentos relevantes.
Limitações
Ao integrar o Cloud Storage com o ADK, tenha em mente as 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 de artefatos duráveis e payloads grandes. No entanto, o uso do Cloud Storage para atualizações de estado de alta frequência e baixa latência pode introduzir latência. Por exemplo, o rastreamento de cada turno em uma troca de conversas rápidas pode ser mais lento do que o uso de caches ou bancos de dados na memória.
- 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, será necessário implementar 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 aplicativo Python, consulte o guia de integração do ADK.