> For the complete documentation index, see [llms.txt](https://docs.digibee.com/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.digibee.com/documentation/resources/pt-br/ai-practical-examples/how-to-agent-component-and-mcp-server-v1.md). # Como consultar um nome em um banco de dados usando um MCP Server e um Agent Component Neste caso de uso, você vai configurar um Agent para acionar uma ferramenta MCP e retornar um resumo baseado nos registros do banco de dados. Você vai configurar: * Uma ferramenta **buscar-pessoas** exposta por um pipeline MCP Server. * Um pipeline Agent que aciona essa ferramenta automaticamente. {% hint style="info" %} Para reproduzir este exemplo, você precisa de um **banco de dados** com uma tabela de pessoas e das credenciais adicionadas como uma [**Conta**](/documentation/developer-guide/pt-br/development-cycle/build-overview/accounts.md) na Digibee. {% endhint %} ## **Passo a passo** {% stepper %} {% step %} ### Expor o banco de dados como uma ferramenta MCP O primeiro passo é criar um pipeline MCP Server que disponibilize sua consulta ao banco de dados como uma ferramenta. É isso que o Agent chamará depois. #### **Criar o pipeline MCP Server** Crie um pipeline chamado **`mcp-buscar-nome-bd`** (o nome deve ser único no seu realm; se ele já existir, escolha outro). Depois abra a configuração do trigger e selecione [**MCP Server**](/documentation/connectors-and-triggers/pt-br/triggers/web-protocols/mcp-server.md) como o tipo. Dentro das configurações do trigger: 1. Clique em **Adicionar Ferramenta** para criar uma nova ferramenta. 2. Preencha os seguintes campos: * **Nome da Ferramenta:** `buscar-pessoas` * **Descrição:** "Busca de pessoas em um banco de dados" * Você pode deixar os campos de schema em branco por agora. 3. Ative as opções de segurança: * **External API:** Torna o pipeline acessível por uma URL pública. * **API Key:** Garante que o endpoint exija autenticação. Depois de salvar, o pipeline cria automaticamente dois caminhos que levam para conectores [**Block Execution**](/documentation/connectors-and-triggers/connectors/logic/block-execution.md): * **buscar-pessoas**: Executado quando a ferramenta existe. * **Tool Not Found**: Executado quando o Agent chama uma ferramenta inexistente. Vamos configurar ambos. {% endstep %} {% step %} ### Implementar a lógica da consulta ao banco de dados O caminho **buscar-pessoas** é onde o trabalho real acontece. Aqui, conectamos ao banco de dados e executamos a consulta usando valores enviados pelo Agent. #### **Configurar o caminho buscar-pessoas** Passe o mouse sobre o conector **Block Execution** desse caminho e clique em [**OnProcess**](/documentation/developer-guide/pt-br/development-cycle/build-overview/pipelines/subpipelines.md#onprocess) para definir o que acontece quando a ferramenta é executada. Você verá um [**JSON Generator**](/documentation/connectors-and-triggers/pt-br/connectors/tools/json-generator.md) padrão. Remova-o e adicione um conector [**DB V2**](/documentation/connectors-and-triggers/pt-br/connectors/structured-data/db-v2.md) configurado da seguinte forma: **Aba General** * **Account:** Selecione a conta do banco adicionada anteriormente na Plataforma. **Aba Operation** * **Type:** `Query` * **Database URL:** Exemplo:\ `jdbc:mysql://34.224.165.98/db-training` * **SQL Statement:** Exemplo: ```sql select * from clientes where name = {{ message.arguments.name }} ``` Esse valor dinâmico vem da chamada da ferramenta. Quando o Agent invoca `buscar-pessoas`, ele envia um objeto como: ```json { "arguments": { "name": "João Souza" } } ``` A expressão `{{ message.arguments.name }}` extrai esse valor e o usa diretamente na consulta SQL. {% endstep %} {% step %} ### Fornecer uma mensagem clara quando o nome da ferramenta estiver incorreto Abra o caminho **Tool Not Found**, passe o mouse sobre o **Block Execution** e clique em **OnProcess**. Dentro do fluxo, ajuste o conector [**Throw Error**](/documentation/connectors-and-triggers/pt-br/connectors/tools/throw-error.md). Você pode personalizar a mensagem, mas se deixar como padrão, o MCP Server retorna automaticamente: * **HTTP 404** * **Message:** `Tool not found` Isso é útil para depuração caso a configuração do Agent faça referência a uma ferramenta incorreta. {% endstep %} {% step %} ### Testar o pipeline MCP Antes de conectá-lo ao Agent, faça um teste rápido no [**Painel de Execução**](/documentation/developer-guide/pt-br/development-cycle/build-overview/canvas/execution-panel.md). Use: ```json { "tool": "buscar-pessoas", "arguments": { "name": "João Souza" } } ``` Um resultado bem-sucedido conterá o registro consultado: {% code overflow="wrap" expandable="true" %} ```json { "data": [ { "uf": "RJ", "codigo": 7676, "cidade": "Rio de Janeiro", "logradouro": "Rua Visconde de Pirajá", "name": "João Souza", "due_date": 1724112000000, "created_at": 1718717592000, "email": "joao.souza@example.com", "cep": "22410-003" } ], "updateCount": 0, "rowCount": 1 } ``` {% endcode %} Se aparecerem dados, a conexão com o banco, a chamada da ferramenta e a consulta SQL estão funcionando corretamente. Certifique-se de **salvar o seu pipeline**. {% endstep %} {% step %} ### Proteger e fazer deploy do endpoint MCP #### **Criar uma Chave de API** Abra **Configurações** na Plataforma e vá até [**Consumers (Chaves de API)**](/documentation/developer-guide/pt-br/platform-administration/settings/api-keys-consumers.md). Você pode criar um novo consumer ou adicionar o pipeline **`mcp-buscar-nome-bd`** a um existente. Copie a **Chave de API** gerada. O Agent vai usá-la depois. #### **Fazer o deploy do pipeline** Abra a página **Run**, procure o pipeline, crie e confirme a [**Implantação**](/documentation/developer-guide/pt-br/development-cycle/overview/deployment/deployments.md). Após o deploy, abra os detalhes do pipeline e copie a **URL pública do endpoint MCP** (termina com `/mcp`). Você vai colá-la na ferramenta do Agent. {% endstep %} {% step %} ### Registrar a conta do provedor de LLM Antes de configurar seu Agent, registre a conta do provedor de LLM que será usada. Para isso: 1. Crie uma chave de API no seu provedor LLM (OpenAI no exemplo). 2. Na Plataforma, registre-a como uma conta do tipo [**Secret Key**](/documentation/developer-guide/pt-br/development-cycle/build-overview/accounts.md#secret-key). {% endstep %} {% step %} ### Criar o pipeline do Agent Agora vamos criar a parte do fluxo que se comunica com o usuário. O Agent vai receber um nome, chamar a ferramenta MCP, recuperar os dados e resumi-los. #### **Configurar o pipeline** Crie um pipeline chamado **`api-buscar-pessoas-mcp`** (o nome deve ser único no seu realm; se ele já existir, escolha outro). Depois configure o trigger como [**REST**](/documentation/connectors-and-triggers/pt-br/triggers/web-protocols/rest.md) e faça as seguintes alterações: * Mantenha apenas o método `GET` ativo. * Ative estas opções de segurança: * **External API:** Expõe o pipeline com uma URL pública. * **API Key:** Requer autenticação para acessar o endpoint. {% hint style="info" %} Lembre-se de criar uma Chave de API para esse pipeline em **Consumers (Chaves de API)**. Você pode reutilizar o consumer criado no [passo 5](#proteger-e-fazer-deploy-do-endpoint-mcp). {% endhint %} Logo após o trigger, adicione um [**JSON Generator**](/documentation/connectors-and-triggers/pt-br/connectors/tools/json-generator.md) com: ```json { "arguments": {{ message.queryAndPath }} } ``` Isso garante que todos os parâmetros de query e de path enviados na requisição `GET` sejam mapeados corretamente para um objeto JSON. Depois, adicione o [**Agent Component**](/documentation/connectors-and-triggers/pt-br/connectors/ai-tools/llm.md). {% endstep %} {% step %} ### Configurar o Agent Component Dentro da configuração do Agent Component: * **Modelo:** OpenAI – GPT-4.1 Mini (bom custo-benefício para este exemplo) * **Mensagem do Sistema:** {% code overflow="wrap" %} ``` Você é um assistente que pode consultar informações sobre pessoas em um banco de dados. Você tem acesso a uma ferramenta chamada "buscar-pessoas", que recupera registros com base no nome da pessoa. Quando alguém pedir informações sobre alguém, chame a ferramenta "buscar-pessoas" usando o nome correto como entrada. Se a ferramenta retornar dados, resuma claramente os principais detalhes. ``` {% endcode %} * **Mensagem do Usuário:** ``` Encontre informações sobre {{ message.arguments.name }} no banco de dados. ``` {% endstep %} {% step %} ### Adicionar a ferramenta ao Agent Crie uma nova ferramenta no Agent: * **Nome:** `buscar-pessoas`\ *(deve ser o nome exato da ferramenta criada no MCP Server)* * **URL do Servidor:** Cole o endpoint MCP implantado, copiado no passo 5. Exemplo: ``` https://test.godigibee.io/pipeline/enablement/v1/mcp-buscar-nome-bd/mcp ``` * **Cabeçalhos:** Adicione um par de chave-valor e cole a API Key copiada no passo 5. Exemplo: ``` apikey: 7f3c1e9b4d2a47c8a1f0e6b29c5d803f ``` Com isso, o Agent já consegue acessar o endpoint MCP com segurança. Agora você pode **salvar esse pipeline**. {% endstep %} {% step %} ### Executar o caso de uso ponta a ponta #### **Dentro do Painel de Execução** Para testar o fluxo dentro da Digibee, abra o [**Painel de Execução**](/documentation/developer-guide/pt-br/development-cycle/build-overview/canvas/execution-panel.md) do pipeline **`api-buscar-pessoas-mcp`** e envie: ```json { "queryAndPath": { "name": "João Souza" } } ``` Veja o que acontece nos bastidores: 1. O Agent lê o nome. 2. Ele decide chamar a ferramenta `buscar-pessoas`. 3. O pipeline MCP recebe a chamada da ferramenta e executa a consulta SQL. 4. O resultado é retornado ao Agent. 5. O Agent escreve um resumo simplificado em linguagem natural. Exemplo: {% code overflow="wrap" expandable="true" %} ```json { "body": { "text": "Encontrei informações sobre João Souza. Ele reside no Rio de Janeiro, especificamente na Rua Visconde de Pirajá, CEP 22410-003. Seu e-mail é joao.souza@example.com. Ele está registrado em nosso banco de dados desde a data UNIX 1718717592000 e tem uma data de vencimento registrada como 1724112000000." }, "tokenUsage": { "inputTokenCount": 407, "outputTokenCount": 106, "totalTokenCount": 513 } } ``` {% endcode %} #### **Em uma ferramenta de testes de API** Para testar o caso de uso fora da Digibee, faça o deploy do pipeline `api-buscar-pessoas-mcp` (da mesma forma que você fez com `mcp-buscar-nome-bd`) e copie o endpoint. Em seguida, siga estes passos: 1. Abra sua ferramenta de testes de API (por exemplo, Postman). 2. Selecione o método `GET`. 3. Cole o endpoint (por exemplo: `https://test.godigibee.io/pipeline/enablement/v1/api-buscar-pessoas-mcp`). 4. Em **Params**, adicione o seguinte par de chave–valor: * `name`: `João Souza` (substitua por uma informação disponível no seu banco de dados) 5. Em **Headers**, adicione o seguinte par de chave–valor: * `apikey`: `7f3c1e9b4d2a47c8a1f0e6b29c5d803f` (substitua pela Chave de API criada para o pipeline `api-buscar-pessoas-mcp`) 6. Clique em **Send**. Exemplo de resposta: {% code overflow="wrap" expandable="true" %} ```json { "body": { "text": "Encontrei informações sobre João Souza. Ele reside no Rio de Janeiro, especificamente na Rua Visconde de Pirajá, CEP 22410-003. Seu e-mail é joao.souza@example.com. Ele está registrado em nosso banco de dados desde a data UNIX 1718717592000 e tem uma data de vencimento registrada como 1724112000000." }, "tokenUsage": { "inputTokenCount": 353, "outputTokenCount": 118, "totalTokenCount": 471 } } ``` {% endcode %} {% endstep %} {% endstepper %} ## **Configurações adicionais do Agent para melhorar a precisão** Depois que o seu Agent estiver funcionando, você pode aumentar a consistência ajustando parâmetros como temperatura, top-p, top-k e a validação opcional por Esquema JSON. Temperaturas mais baixas ajudam a reduzir alucinações, enquanto os esquemas garantem que o resultado sempre siga a estrutura esperada. Essas configurações são opcionais, mas recomendadas para cenários de produção. Para explicações completas e detalhes sobre os parâmetros, consulte a documentação completa do [**Agent Component**](/documentation/connectors-and-triggers/pt-br/connectors/ai-tools/llm.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.digibee.com/documentation/resources/pt-br/ai-practical-examples/how-to-agent-component-and-mcp-server-v1.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.