Pular para o conteúdo principal

Agentes Gerenciados

Avançado
What you'll learn
  • Entender o que um loop de agente gerenciado (hospedado pela Anthropic) faz por você
  • Separar os dois objetos centrais: um Agent versionado vs uma Session por execução
  • Injetar segredos com segurança usando Vaults — sem que o modelo jamais os veja
  • Colocar um agente em um agendamento cron com Scheduled Deployments — sem agendador para hospedar
  • Saber quando o gerenciado supera um loop personalizado, e as proteções que ainda se aplicam

Se construir seu próprio loop de agente é mais infraestrutura do que você quer manter, um agente gerenciado (hospedado pela Anthropic) roda o loop por você — para que você foque na tarefa do agente, e não no encanamento das sessões, retentativas, estado e agendamento.

Os dois objetos: Agent vs Session​

Este é o modelo mental do qual tudo o mais depende. Eles são separados de propósito.

  • Um Agent é uma configuração persistida e versionada — modelo, system prompt, ferramentas, servidores MCP e skills. Você o cria uma vez. Cada atualização cria uma nova versão imutável.
  • Uma Session é uma instância de runtime — uma execução que aponta para um agente por ID. A configuração vive no agente, nunca na sessão.
Pro tip

As sessões fixam (pin) na versão do agente com a qual foram criadas: sessões em execução mantêm sua versão, novas sessões recebem a mais recente. É assim que você publica mudanças de configuração sem quebrar o trabalho em andamento.

O que o "gerenciado" oferece a você​

Em vez de construir e hospedar o loop manualmente, você ganha blocos de construção hospedados:

  • Sessions — execuções persistentes que você cria por execução e retoma; transmitem eventos por SSE.
  • Environments — infraestrutura de container, seja cloud (hospedado pela Anthropic) ou self_hosted (as ferramentas executam na sua própria VPC). Um container por sessão é o espaço de trabalho do agente.
  • Memory stores — estado persistente entre sessões, com versionamento e redação, sem que você precise conectar um banco de dados.
  • Vaults — segredos para autenticação MCP e outros serviços.
  • Scheduled deployments — agentes que rodam em um agendamento cron, sem supervisão.

Crie um agente (configuração versionada) e depois rode uma sessão contra ele

# 1. Create the agent once
POST /v1/agents        -> returns $AGENT_ID
# 2. Each execution is a session pinned to that agent
POST /v1/sessions      { "agent": "$AGENT_ID" }

Vaults: segredos que o modelo nunca vê​

Um agente autônomo muitas vezes precisa de uma chave de API — mas o modelo nunca deveria lê-la. As credenciais do Vault (mcp_oauth, static_bearer, environment_variable) são substituídas no egress: uma credencial environment_variable é injetada no sandbox no momento da execução e nunca fica visível para o modelo.

Watch out

Este é o padrão seguro para dar a um agente acesso poderoso. Não cole chaves no system prompt ou em uma mensagem — elas passam a fazer parte do contexto que o modelo (e seus logs) podem ver. Coloque-as em um vault.

Scheduled deployments: um agente em um cron​

Um deployment anexa um agendamento cron a um agente. Quando o agendamento dispara, ele inicia uma sessão nova e completa sua tarefa — sem nenhum agendador para você construir ou hospedar. Bom para uma sincronização de dados noturna, uma varredura de conformidade semanal ou um resumo diário.

Guided walkthrough1 of 4
  1. POST /v1/deployments com agent, environment_id, initial_events (deve incluir um user.message) e um schedule: uma expressão cron POSIX mais um timezone IANA.

Uma varredura de conformidade semanal, às sextas-feiras às 20:00 no horário de Nova York

POST /v1/deployments
{
"name": "Weekly compliance scan",
"agent": "$AGENT_ID",
"environment_id": "$ENVIRONMENT_ID",
"initial_events": [
  {"type": "user.message", "content": [{"type": "text", "text": "Run the compliance scan and summarize findings."}]}
],
"schedule": {"type": "cron", "expression": "0 20 * * 5", "timezone": "America/New_York"}
}
Pro tip

Cron é minute hour day-of-month month day-of-week, com granularidade de minuto. O horário de verão (DST) usa semântica de relógio de parede: um horário que não existe na transição de adiantamento é pulado; um horário que ocorre duas vezes na transição de atraso dispara duas vezes. Escolha um timezone e uma hora que evitem essas bordas para qualquer coisa sensível.

Quando escolher gerenciado vs personalizado​

Escolha gerenciado quando…Escolha um loop personalizado / SDK quando…
Você quer hospedagem, estado, agendamento e segredos resolvidosVocê precisa de controle total sobre o loop e as ferramentas
Você está prototipando rapidamenteVocê tem necessidades rígidas de infra/conformidade personalizadas
A simplicidade operacional importa mais que o controleVocê está integrando profundamente na sua própria stack

É um espectro — chamada única → workflow → agente personalizado (SDK) → gerenciado. Comece tão simples quanto a tarefa permitir; suba de nível apenas quando precisar.

As mesmas proteções se aplicam​

Hospedado ou não, um agente autônomo ainda realiza ações. Mantenha privilégio mínimo, custo/iterações limitados e aprovação humana para passos arriscados — veja Protegendo Agentes e Endurecendo Execuções Autônomas.

Key takeaways
  • Agentes gerenciados entregam o loop, as sessões, os environments, a memória, os vaults e o agendamento para que você foque na tarefa
  • Um Agent é configuração versionada; uma Session é uma execução que fixa em uma versão — a configuração vive no agente, não na sessão
  • As credenciais environment_variable do Vault são injetadas na execução e nunca ficam visíveis para o modelo — a forma segura de dar segredos a um agente
  • Um scheduled deployment é uma expressão cron + timezone IANA; cada disparo cria uma execução, e o unpause não recupera os triggers perdidos
  • O gerenciado fica na ponta hospedada de chamada única -> workflow -> personalizado -> gerenciado; as proteções de autonomia ainda se aplicam

Teste você mesmo​

Teste você mesmo

0/3
  1. Qual é a diferença entre um Agent e uma Session?
  2. Como você deve dar a um agente gerenciado uma chave de API de que ele precisa?
  3. Um scheduled deployment ficou pausado por dois dias e depois foi reativado (unpause). O que acontece com os triggers que teriam disparado enquanto estava pausado?

Próximo​