A API Managed Agents na Agent Platform permite criar agentes gerenciados e autônomos com uma única chamada de API. Com o suporte do Antigravity, cada agente é executado em um ambiente de sandbox, onde raciocina, planeja, usa habilidades de agente, executa código, pesquisa na Web e lê e grava arquivos.
Arquitetura do sistema
A API Managed Agents na Agent Platform usa duas interfaces principais:
| API | Descrição |
|---|---|
| API Agents | O plano de controle para gerenciar agentes. Use-o para criar agentes com base em configurações e configurar os ambientes de execução deles, incluindo a montagem de fontes de dados externas e a definição de listas de permissões de rede. O sistema aplica essas configurações ao ambiente de execução de sandbox do agente. A conexão de fontes de dados e ferramentas externas requer autenticação, com limitações descritas em Segurança e práticas recomendadas. |
| API Interactions | Esse é o plano de dados, que serve como a interface principal para se comunicar e interagir com os agentes implantados no ambiente de execução. Ele se conecta ao agente criado usando a API Agents. |
Para maior segurança, cada agente opera em um ambiente de sandbox isolado. Quando você personaliza o ambiente com fontes externas, como o Cloud Storage, o sistema carrega esses arquivos diretamente no sistema de arquivos do contêiner sob demanda, e o agente pode gravar os resultados de volta no Cloud Storage. Para mais informações, consulte a referência da API Managed Agents no ambiente de sandbox da plataforma de agentes.
Segurança e práticas recomendadas
Por padrão, cada agente executa ações em um ambiente de sandbox sem acesso a sistemas, redes ou credenciais externos. O agente só pode interagir com os arquivos, pacotes e dados dentro do próprio sandbox.
Isso significa que, por padrão, o agente não pode fazer chamadas de rede, acessar bancos de dados ou alcançar qualquer infraestrutura de produção.
Qualquer conectividade além do sandbox precisa ser explicitamente configurada por você, o desenvolvedor. Para mais informações, consulte Configurar o acesso à rede.
Acesso à rede
Ative essa opção apenas quando o caso de uso exigir e limite o acesso o máximo possível.
Quando você ativa o acesso à rede para um ambiente, o agente pode acessar APIs externas, clonar repositórios públicos e fazer o download de pacotes. Antes de ativar o acesso à rede, considere o seguinte:
- Evite expor endpoints sensíveis. Não direcione o agente para serviços internos, painéis de administração ou bancos de dados, a menos que você tenha analisado os riscos e esteja preparado para monitorar a atividade do agente.
- Analisar as ações do agente. Quando o acesso à rede estiver ativado, monitore as interações do agente, especialmente durante o desenvolvimento inicial, para verificar se ele está acessando apenas os recursos pretendidos.
Práticas recomendadas para credenciais
Se o fluxo de trabalho exigir que o agente se autentique com serviços externos, como servidores MCP, você será responsável por provisionar e definir o escopo dessas credenciais. Siga estas diretrizes para reduzir os riscos:
- Use credenciais de privilégio mínimo. Crie contas de serviço ou chaves de API com as permissões necessárias para o agente. Evite transmitir credenciais com acesso amplo ou administrativo.
- Dê preferência a tokens de curta duração. Sempre que possível, use credenciais ou tokens com limite de tempo que expiram, em vez de chaves de API de longa duração.
- Nunca transmita credenciais que você não quer que o agente use. O agente pode usar qualquer credencial a que tenha acesso para concluir a tarefa que você atribuiu. Forneça apenas credenciais com o escopo completo de acesso que você quer conceder.
- Alterne as credenciais regularmente. Trate as credenciais compartilhadas com o agente da mesma forma que você trataria qualquer credencial programática: faça a rotação delas em um cronograma regular.
Conectar ferramentas e APIs externas
A API Agents permite conectar ferramentas e APIs externas (como servidores MCP) para ampliar as capacidades do agente. Ao fazer isso:
- Avalie as fontes das ferramentas com cuidado. Conecte apenas ferramentas de fontes confiáveis. Uma ferramenta maliciosa ou mal escrita pode expor dados ou realizar ações não intencionais.
- Defina o escopo das permissões de ferramentas. Configure as ferramentas com as permissões mínimas necessárias para seu caso de uso. Se uma ferramenta for compatível com o modo somente leitura, use-o, a menos que o acesso de gravação seja necessário.
- Primeiro, teste de forma isolada. Antes de conectar uma ferramenta a uma fonte de dados de produção, teste-a com dados de amostra ou sintéticos para verificar se o agente a usa conforme o esperado.
Supervisão humana
Os agentes podem raciocinar, planejar e executar fluxos de trabalho de várias etapas com um alto grau de autonomia. Embora isso seja poderoso, também significa que você precisa aplicar a supervisão adequada, principalmente para tarefas que modificam dados ou interagem com sistemas externos.
Sempre verifique as saídas críticas, como código gerado, transformações de dados ou mudanças de configuração, antes de implantá-las.
Suporte e feedback
Envie um e-mail para o grupo de discussão público em
managed-agents-in-agent-platform@google.com para receber suporte e feedback sobre a
API Managed Agents na Agent Platform.
A seguir
Criar e gerenciar agentes
Saiba como criar, atualizar, listar, receber e excluir agentes usando a API REST.
API Managed Agents no ambiente de sandbox da Agent Platform
Saiba mais sobre o contêiner de sandbox isolado, as permissões e os pacotes/ferramentas pré-instalados.
Avaliar agentes
Saiba como avaliar agentes criados com a API Managed Agents usando o serviço de avaliação de IA generativa.