Crie um agente detalhado

Visão geral

O MongoDB Atlas Agent Engine SDK fornece uma superfície voltada para o desenvolvedor para a criação de agentes detalhados. Os agentes profundos são agentes de IA capazes de operações de sistema de arquivos, execução de shell e processamento de várias etapas, com todas as entradas e saídas roteadas por meio da camada de segurança auditada da plataforma.

Dica

Para saber mais sobre agentes profundos, consulte a visão geral de agentes profundos na documentação do LangChain.

Os autores do agente interagem com três componentes principais do SDK:

App.deep_agent(): O método de fábrica para definir e conectar um agente secreto.
Manifestos de habilidades: conjuntos de instruções que o agente pode descobrir e invocar no tempo de execução.
Backend da sandbox de ferramentas: o backend que direciona todas as chamadas de ferramentas pelo caminho de execução seguro da plataforma.

Pré-requisitos

Antes de criar um agente detalhado, você deve adicionar a dependência deepagents ao seu arquivo pyproject.toml e ativar recursos de agente detalhado no arquivo agent.yaml.

Atualizar dependências

Para criar um agente detalhado, adicione o pacote deepagents ao arquivo pyproject.toml do seu projeto:

dependencies = [
    "deepagents==0.5.3",
    ... # other dependencies
]

O pacote deepagents é uma dependência opcional do pacoteagent-engine-sdk-langgraph. O SDK importa o pacote deepagents somente quando o aplicativo chama a função App.deep_agent(), então você deve declará-la explicitamente em seu projeto.

Atualizar sinalizadores de recurso

Habilite funcionalidades de agente detalhado em seu agent.yaml adicionando o seguinte sinalizador ao seu arquivo agent.yaml:

features:
  deep_agent: true
  ... # other features

Esse sinalizador instrui a sandbox da ferramenta a registrar o sistema de arquivos integrado e os manipuladores de shell nos quais os agentes profundos confiam.

Observação

Os agentes TypeScript constroem agentes profundos com o método de fábrica equivalente app.deepAgent(), que requer a mesma configuração features.deep_agent: true. Os exemplos nesta página usam Python.

Método deep_agent()

O método App.deep_agent() é o principal ponto de entrada para autores de agente . Ele cria um gráfico LangChain compilado que se integra ao caminho de transmissão gRPC e SSE da plataforma, ao checkpointing apoiado MongoDB e à classe AgentEngineToolSandboxBackend para execução de ferramentas de sandbox.

O método executa as seguintes tarefas automaticamente:

Utiliza a classe AgentEngineToolSandboxBackend como a sandbox padrão
Envolve o LLM de nível superior e todos os modelos SubAgent na classe SecureWrappedLLM para impor o caminho do LLM auditado da plataforma
Passa o checkpointer do MongoDB para um estado de execução durável
Retorna um gráfico compilado compatível com o caminho de transmissão gRPC/SSE existente e a solicitação de API POST /api/v1/executions/{execution_id}/resume

Parâmetros

O método App.deep_agent() aceita os seguintes parâmetros:

Parâmetro	Tipo	Obrigatório	Descrição
`llm`	LLM	Sim	A instância do modelo de idioma a ser usada como modelo primary do agente. A plataforma envolve isso na classe `SecureWrappedLLM` automaticamente.
`tools`	Lista	No	Uma lista de objetos de ferramenta compatíveis com LangChain disponíveis para o agente. Para saber mais sobre as ferramentas do LangChain, consulte a documentação do LangChain.
`subagents`	Lista	No	Uma lista de instâncias da classe `SubAgent`. Cada atributo `SubAgent.model` deve ser uma instância LLM, não uma string. As referências de modelo baseadas em string ignoram a classe `SecureWrappedLLM` e são rejeitadas no momento da validação.
`skills`	list[str]	No	Uma lista de caminhos para diretórios de habilidades. Cada diretório deve conter um arquivo `SKILL.md` válido. Cada caminho deve ser um `str`, não um objeto`pathlib.Path` . Para saber mais sobre arquivos SKILL.md, consulte a seção Manifestos de habilidade.
`system_prompt`	string	No	Instruções personalizadas do sistema para o agente profundo. Se omitido, o agente usa o prompt padrão da biblioteca `deepagents`.
`middleware`	Lista	No	Middleware adicional, que é executado após o middleware padrão de recuperação de interrupção e aninhamento durável do SDK.
`checkpointer`	any	No	Ponto de verificação LangGraph para persistência de estado. O padrão é `app.checkpointer()`. Passe `None` para desativar o checkpointing ou uma instância `BaseCheckpointSaver` para usar um checkpoint personalizado.
`store`	any	No	Armazenamento LangGraph usado para habilidades e outros dados compartilhados.
`backend`	any	No	Backend para operações de sistema de arquivos e shell. O padrão é a classe`AgentEngineToolSandboxBackend` . Um backend personalizado ignora o caminho de E/S auditado da plataforma. Para saber mais, consulte Ferramenta Sandbox Backend.

Crie um agente detalhado com habilidades

Para criar um agente detalhado que invoque habilidades, passe uma lista de caminhos do diretório de habilidades para o parâmetro skills do método App.deep_agent().

O exemplo a seguir modifica a função personalizada @app.entrypoint para criar um agente detalhado com uma única ferramenta e um diretório de habilidade:

from agent_engine_sdk_langgraph import App
app = App()
@app.entrypoint
def build_agent():
    return app.deep_agent(
        llm=my_llm,
        tools=[my_tool],
        subagents=[],
        skills=["skills/security-review"],
    )

Importante

Não encapsular sua instância LLM com o método app.llm() antes de passá-la para o método app.deep_agent(). O método deep_agent() envolve o LLM na classe SecureWrappedLLM internamente. A chamada do método app.llm() primeiro registra o ID LLM __default__ duas vezes e o agente falha ao iniciar.

Validações de segurança

No momento da inicialização, o método App.deep_agent() executa as seguintes verificações e gera um erro se uma delas falhar:

Verifique se há referências ao modelo de string na classeSubAgent : cada atributo SubAgent.model deve ser uma instância LLM e não uma string. Os nomes dos modelos de string ignoram a classe SecureWrappedLLM e a plataforma rejeita o agente. O método verifica até 10 níveis de aninhamento.
Verifique se há um parâmetro backend fornecido manualmente: a plataforma possui a sandbox e impõe a classe AgentEngineToolSandboxBackend como backend. O fornecedor de um backend personalizado ignora a sandbox da plataforma e a plataforma rejeita o backend.

Observação

O método App.deep_agent() executa as verificações anteriores antes que a biblioteca LangChain deepagents compila o gráfico do agente . Se uma das verificações falhar, o agente não será iniciado.

Além dessas verificações, o método App.deep_agent() envolve automaticamente a instância LLM passada para o parâmetro llm e todos os atributos SubAgent.model na classe SecureWrappedLLM antes que a biblioteca deepagents compila o gráfico.

Manifestos de habilidades

As habilidades são conjuntos de instruções reutilizáveis que você fornece a um agente secreto. Cada habilidade reside em seu próprio subdiretório e é descrita por um arquivo SKILL.md com o frontmatter YAML. A plataforma lê o frontmatter na inicialização do agente para validar e expor a habilidade ao LLM.

Estrutura de diretório de habilidades

As habilidades estão localizadas dentro da seguinte estrutura de diretório, onde o nome do diretório corresponde ao campo name no frontmatter:

<workspace-directory>/
└── skills/
    └── <skill-name>/
        └── SKILL.md

Os caminhos de habilidade passados para o parâmetro skills são relativos ao diretório do espaço de trabalho do seu agente, que é o diretório que contém seu arquivo agent.yaml.

Formato SKILL.md

Um arquivo SKILL.md válido deve começar com YAML frontmatter. O exemplo a seguir é um modelo para um arquivo SKILL.md válido:

---
name: <skill-name>
description: <one-sentence description for LLM discovery>
---
# Skill Title
Detailed instructions or reference material for the agent...

Você deve incluir os seguintes campos no frontmatter do YAML:

Campo	Obrigatório	Descrição
`name`	Sim	O nome da habilidade. Deve corresponder exatamente ao nome do diretório pai.
`description`	Sim	O LLM usa esta breve descrição para decidir quando invocar a habilidade. As habilidades que não possuem `description` são ignoradas pela plataforma com um aviso na inicialização do agente e não estão disponíveis para agente.

Observação

O arquivo SKILL.md deve conter apenas caracteres UTF-8 válidos. Os arquivos que não podem ser lidos como UTF-8 pela plataforma são ignorados na inicialização do agente sem causar uma falha.

Passando habilidades para o agente

O exemplo a seguir passa uma lista de caminhos do diretório de habilidades para o método App.deep_agent():

agent = app.deep_agent(
    llm=my_llm,
    tools=[],
    skills=["skills/security-review", "skills/style-guide"],
)

Sandbox Backend da Ferramenta

A classe AgentEngineToolSandboxBackend implementa o protocolo SandboxBackendProtocol. O backend roteia todas as chamadas de sistema de arquivos e ferramentas de shell do gráfico detalhado do agente por meio do manipulador de sandbox de ferramentas da plataforma usando a classeSecureToolWrapper. Não é necessário instanciar ou configurar a classe AgentEngineToolSandboxBackend diretamente, pois o método App.deep_agent() a injeta automaticamente.

Observação

A classe AgentEngineToolSandboxBackend é uma dependência opcional e não é reexportada da raiz do pacote . Se precisar referenciá-lo diretamente, importe-o explicitamente. O exemplo a seguir demonstra como importar a classe:

from agent_engine_sdk_langgraph.backends.tool_sandbox import AgentEngineToolSandboxBackend

Operações suportadas

As operações da classe AgentEngineToolSandboxBackend são invocadas automaticamente pelo agente no tempo de execução e não são chamadas diretamente pelos autores do agente . A classe AgentEngineToolSandboxBackend suporta as seguintes operações, cada uma exposta ao LLM como uma ferramenta filesystem_* ou shell_execute correspondente:

(operação)	Descrição
`ls`	Lista arquivos e diretórios em um determinado caminho
`read`	Lê o conteúdo de um arquivo
`write`	Escreve conteúdo em um arquivo
`edit`	Aplica uma edição a um arquivo existente
`glob`	Encontra arquivos correspondentes a um padrão global
`grep`	Pesquisa um padrão dentro dos arquivos
`execute`	Executa um comando shell no sandbox
`download_files`	Baixa arquivos da sandbox para o chamador

Error Handling

O backend classifica todos os erros antes de exibi-los no gráfico do agente para que o agente possa decidir se deseja tentar novamente a operação. A tabela a seguir mostra possíveis classificações de erro e suas causas:

Classificação	Exemplo de causas
Repetitivo	Erros transitórios de rede ou entrada e saída como `ConnectionError`, `OSError` ou `TimeoutError`.
Não repetível	`PolicyDeniedException`: a operação foi negada pela política de segurança da plataforma. O agente não pode tentar a operação novamente. `RuntimeError`: o backend foi usado fora de um contexto válido de sandbox de agente , como em um script ou teste local. Esse erro evita loops infinitos de tentativas em caso de configuração incorreta.

A plataforma remove todos os caminhos internos do espaço de trabalho de todas as mensagens de erro antes que elas sejam exibidas ao agente.

Filesystem Sandbox

Agentes profundos operam dentro de um sistema de arquivos em sandbox. A sandbox contém as seguintes camadas:

Espaço de trabalho gravável (WORKSPACE_DIR): o padrão é o diretório /tmp/agent-workspace. Durante as sessões de sandbox do agente , a sandbox limita o acesso do agente ao caminho WORKSPACE_DIR/.sessions/<session-hash>/ para que as sessões simultâneas permaneçam isoladas. Use caminhos relativos ou caminhos no diretório /tmp para arquivos gerados.
Raízes de recursos somente leitura (READONLY_RESOURCE_ROOTS): preenchidas a partir da variável de ambiente AGENTIC_AGENT_WORKDIR e do diretório skills/. Essa camada permite que o agente leia arquivos SKILL.md dentro e fora do espaço de trabalho por sessão, para que ele possa carregar o conteúdo da habilidade sob demanda.

Importante

Não defina a variável de ambiente WORKSPACE_DIR para o diretório de origem do agente , como o diretório /app. Se você definir a variável WORKSPACE_DIR para o diretório de origem do agente , o agente tornará os arquivos de habilidade inacessíveis no tempo de execução e lançará um erro Path escapes workspace sandbox.

Para alterar o diretório do espaço de trabalho, defina a variável de ambiente AGENTIC_AGENT_WORKDIR:

# .env
AGENTIC_AGENT_WORKDIR=/app
# Do NOT add: WORKSPACE_DIR=/app

Voltar

Execute agentes localmente