Para agentes de IA: um índice de documentação está disponível em https://www.mongodb.com/pt-br/docs/llms.txt — as versões de markdown de todas as páginas estão disponíveis anexando .md a qualquer caminho de URL.

Criar FERRAMENTAS a partir de uma especificação OpenAPI

Neste guia, você pode aprender como converter um documento OpenAPI 3.0 em FERRAMENTAS de agente. Use o comando agentengine agent create-tool para compilar o documento em arquivo de conector. Ao criar seu agente, o mecanismo de agente Atlas cria o conector a partir desses arquivos para que seu agente possa chamar as FERRAMENTAS de agente OpenAPI.

Observação

O comando agentengine agent create-tool é experimental. Os sinalizadores, o formato de saída e os formatos de arquivo gerados podem mudar sem aviso prévio.

Sobre esta tarefa

O comando agentengine agent create-tool gera dois arquivos na pasta que você especificar:

  • tool_defs.yaml: O catálogo de FERRAMENTAS que o comando compila a partir do documento OpenAPI. O catálogo inclui nomes de ferramentas, esquema de entrada e o método e caminho HTTP para cada operação.

  • tool.yaml: O arquivo de autoria que vincula o catálogo ao seu ponto de extremidade da API e credenciais, e seleciona quais FERRAMENTAS seu agente expõe. O comando cria a estrutura deste arquivo. Ao regenerar o catálogo, o comando não substitui suas edições no arquivo.

Quando o agente chama uma ferramenta de conector, a ferramenta é executada em um Tool Pod isolado. A chamada passa pelo mesmo portão de aprovação do Orchestration mecanismo que outras FERRAMENTAS. Os valores das credenciais nunca são gravados nos arquivos gerados, e os arquivos fazem referência ao nome de um segredo do workspace.

Você deve passar exatamente uma das seguintes entradas para o comando:

  • --spec: Compila um documento OpenAPI 3.0 em um catálogo e cria um arquivo tool.yaml se nenhum existir. O valor pode ser um arquivo local ou uma URL HTTPS.

  • --tool-defs: Cria apenas o arquivo tool.yaml para um catálogo local existente. O comando não sobrescreve o catálogo.

  • --config: Regenera um catálogo de propriedade local a partir do arquivo tool.yaml que declara o campo source.spec.

Para ver todos os sinalizadores, consulte a documentação da CLI agentengine_create-tool.

Antes de começar

Antes de começar, certifique-se de ter os seguintes recursos:

  • A CLI agentengine instalada e autenticada. Para aprender mais, consulte Instalar e autenticar.

  • Um projeto de agente válido com um arquivo agent.yaml. Para saber mais, consulte Criar um projeto.

  • Docker em execução localmente.

  • Um documento OpenAPI 3.0, seja um arquivo local ou uma URL HTTPS, para a REST API que você deseja chamar.

  • Um Bearer token de autenticação para a REST API.

Passos

1

Gere os arquivos do conector.

No diretório do seu projeto de agente, execute o comando agentengine agent create-tool com o nome do conector e a flag --spec. O exemplo a seguir compila uma especificação na pasta connectors/orders e configura a autenticação com Bearer token:

agentengine agent create-tool orders \  --spec <openapi-document-url-or-path> \  --out-dir connectors/orders \  --auth bearer

O comando nomeia o segredo do workspace para o Bearer token após o conector. Para o conector orders, o nome do segredo é ORDERS_TOKEN. Se você omitir a flag --auth, o comando gera o bloco auth no arquivo tool.yaml a partir dos esquemas de segurança que o documento declara.

O comando usa o primeiro servidor não modelado no documento como a URL base. Se o documento não declarar um servidor, ou se você quiser chamar um ponto de extremidade diferente, adicione o sinalizador --base-url ao comando.

Se o documento contiver operações que o gerador não consegue representar, o comando falha e imprime o nome da operação. Para excluir essas operações, adicione o sinalizador --skip-unsupported ao comando. O comando imprime cada operação ignorada e faz um registro no catálogo.

2

Revise o arquivo tool.yaml.

Abra o arquivo connectors/orders/tool.yaml. O comentário na parte superior do arquivo nomeia o destino do ponto de extremidade e o segredo de credenciais que seu agente deve declarar.

Para limitar quais FERRAMENTAS seu agente pode chamar, liste nomes de ferramentas específicos no campo expose.allow. Se você omitir esta lista, o agente poderá chamar todas as ferramentas geradas. O exemplo a seguir mostra um arquivo tool.yaml que expõe uma ferramenta:

name: orderstool_defs: tool_defs.yamlsource:  type: openapi  base_url: https://api.example.comexpose:  allow: [orders_getOrder]auth:  bearer: ORDERS_TOKEN
3

Registre o conector.

No seu arquivo agent.yaml, adicione uma entrada connectors que aponte para o arquivo tool.yaml. O caminho é relativo ao arquivo agent.yaml.

version: 1connectors:  - source: connectors/orders/tool.yaml
4

Armazene a credencial da API como um segredo de workspace.

Crie um segredo com o nome que o bloco auth no arquivo tool.yaml referencia. Neste exemplo, o nome do segredo é ORDERS_TOKEN. Para aprender como armazenar segredos, consulte Provisionamento de segredos na nuvem.

5

Conceda à ferramenta acesso sandbox ao segredo e à API.

O comentário na parte superior do arquivo tool.yaml relata apenas os requisitos e não concede nenhuma permissão. No seu arquivo agent.yaml, adicione o segredo ao campo sandboxes.tool.secrets e o nome do host da API ao campo sandboxes.tool.network.egress. Mantenha os segredos e destinos que suas outras FERRAMENTAS já usam. O exemplo a seguir adiciona o segredo ORDERS_TOKEN e o hospedar api.example.com:

sandboxes:  tool:    secrets:      - ORDERS_TOKEN    network:      egress_mode: allow_list      egress:        - fqdn: api.example.com          ports: [443]

Substitua api.example.com e 443 pelo nome do host e pela porta da URL base no seu arquivo tool.yaml. Para aprender mais, consulte o Esquema YAML do Agente e Gerenciar Políticas de Saída de Rede.

6

Crie e implante seu agente.

Crie e implante seu agente como de costume. O criar gera o conector a partir de seus arquivos tool.yaml e tool_defs.yaml. Para aprender mais, consulte Criar a imagem do agente.

Comportamento e Limitações

revisar o seguinte comportamento e limitações para FERRAMENTAS de conector geradas:

  • A URL base no arquivo tool.yaml se aplica a cada operação. O gerador ignora entradas servers no nível de caminho e no nível de operação no documento OpenAPI.

  • O gerador lê arquivos locais. A CLI baixar documentos que você especifica por URL sob a política de transporte da plataforma.

  • O gerador oferece suporte a Bearer token, chaves de API e autenticação HTTP Basic. Os itens a seguir estão fora do limite de geração:

    • Aquisição e atualização de token OAuth

    • Login interativo ou de sessão

    • Assinatura por solicitação

    • autenticação apenas com mTLS

    • Uploads de arquivo multipart

  • Um conector trunca respostas maiores que 200,000 bytes decodificados e as marca como truncadas.

  • Cada invocação da ferramenta expira após 30 segundos.

Saiba mais

Consulte a documentação a seguir para aprender mais sobre as FERRAMENTAS OpenAPI:

Voltar
Servidores MCP remotos
Próximo
Adicionar saída de fluxo personalizada ao seu agente
Avalie esta página

Nesta página