Agentes: Crie Assistentes de IA Personalizados

O recurso de AI Agents do LibreChat oferece uma estrutura flexível para a criação de assistentes de IA personalizados, alimentados por diversos provedores de modelos.

Este recurso é semelhante à Assistants API da OpenAI e aos GPTs do ChatGPT, mas com suporte a uma gama mais ampla de modelos e uma implementação sem código (no-code), permitindo que você crie assistentes sofisticados com capacidades especializadas.

Primeiros Passos

Para criar um novo agente, selecione "Agents" no menu de endpoint e abra o painel Agent Builder encontrado no Side Panel.

O formulário de criação inclui:

• Avatar: Faça upload de um avatar personalizado para personalizar seu agente
• Nome: Escolha um nome distinto para o seu agente
• Description: Detalhes opcionais sobre o propósito do seu agente
• Instruções: Instruções de sistema que definem o comportamento do seu agente
• Modelo: Selecione a partir dos provedores e modelos disponíveis

Agentes existentes podem ser selecionados no menu suspenso superior do Painel Lateral.

• Também por menção com "@" na entrada de chat.

Configuração de Modelo

A interface de parâmetros do modelo permite o ajuste fino das respostas do seu agente:

• Temperatura (escala de 0 a 1 para a criatividade da resposta)
• Tokens de contexto máximos
• Máximo de tokens de saída
• Configurações adicionais específicas do provedor

Capacidades dos Agentes

Nota: Todas as capacidades podem ser alternadas através do arquivo de configuração librechat.yaml. Veja docs/configuration/librechat_yaml/object_structure/agents#capabilities para mais informações.

Code Interpreter

Quando ativado, o recurso Code Interpreter permite que seu agente:

• Execute código em várias linguagens, incluindo:
  • Python, JavaScript, TypeScript, Go, C, C++, Java, PHP, Rust e Fortran
• Processe arquivos de forma segura através da API de Code Interpreter do LibreChat
• Execute código sem configuração local, definições ou implantação de sandbox
• Gerencie uploads e downloads de arquivos de forma integrada
• Mais informações sobre a API do Code Interpreter
  • Desenvolvido pelo serviço de código aberto code-interpreter (auto-hospedado)

File Search

A funcionalidade File Search permite:

• Funcionalidade de RAG (Retrieval-Augmented Generation)
• Busca semântica em documentos enviados
• Respostas com reconhecimento de contexto baseadas no conteúdo de arquivos
• Suporte a anexos de arquivos tanto em nível de agente quanto de thread de chat

Contexto de Arquivo

A funcionalidade de File Context permite que seu agente armazene texto extraído de arquivos como parte de suas instruções de sistema:

• Extraia texto mantendo a estrutura e a formatação do documento
• Processar layouts complexos, incluindo texto em várias colunas e conteúdo misto
• Lidar com tabelas, equações e outros conteúdos especializados
• Trabalhe com conteúdo multilíngue
• O texto é armazenado nas instruções do agente no banco de dados
• Nenhum serviço de OCR necessário - Usa análise de texto por padrão com métodos de fallback
• Aprimorado por OCR - Se o OCR estiver configurado, a qualidade da extração melhora para imagens e documentos digitalizados
• Usa a mesma lógica de processamento que "Upload as Text": OCR > STT > text parsing
• Mais informações sobre a configuração de OCR

Nota: O File Context inclui texto extraído nas instruções de sistema do agente. Para perguntas sobre documentos temporários em conversas individuais, use Upload as Text a partir do chat.

Model Context Protocol (MCP)

MCP é um protocolo aberto que padroniza como as aplicações fornecem contexto para Large Language Models (LLMs), atuando como um adaptador universal para ferramentas de IA e fontes de dados.

Para mais informações, consulte a documentação sobre MCP.

Agentes com MCP Tools

1. Configure servidores MCP no seu arquivo librechat.yaml
2. Reinicie o LibreChat para inicializar as conexões
3. Criar ou editar um agente
4. Clique no botão "Add Tools" no painel do Agent Builder para abrir a caixa de diálogo Tools mostrada abaixo
5. Selecione o(s) servidor(es) MCP que você deseja adicionar - cada servidor aparece como uma única entrada
6. Salve suas alterações no agente

Neste exemplo, adicionamos o Spotify MCP server a um agente.

Gerenciando Ferramentas MCP

Assim que um servidor MCP for adicionado a um agente, você poderá ajustar quais ferramentas específicas estarão disponíveis:

• Após adicionar um servidor MCP, expanda-o para ver todas as ferramentas disponíveis
• Marque/desmarque ferramentas individuais conforme necessário
• Por exemplo, o servidor MCP do Spotify fornece cerca de 20 ferramentas (pesquisa, controle de reprodução, gerenciamento de playlists, etc.)
• Esse controle granular permite que você limite os agentes apenas às ferramentas de que eles precisam

Saiba mais:

• Configurando Servidores MCP
• Introdução ao Model Context Protocol

Ferramentas Diferidas

Ferramentas adiadas (deferred tools) permitem que agentes tenham acesso a muitas ferramentas MCP sem carregá-las todas no contexto do LLM antecipadamente. Em vez disso, as ferramentas adiadas são detectáveis em tempo de execução por meio de um mecanismo de Busca de Ferramentas (Tool Search).

Isso é especialmente útil quando um agente tem acesso a muitos servidores MCP com dezenas de ferramentas — carregá-las todas consumiria uma grande parte da janela de contexto e degradaria a qualidade da resposta.

Como funciona:

• Ferramentas marcadas como "deferred" são excluídas do contexto inicial do LLM
• Uma ferramenta ToolSearch é adicionada automaticamente, permitindo que o LLM descubra e carregue ferramentas adiadas sob demanda.
• Uma vez descoberta, a ferramenta fica disponível para o restante da conversa

Configurando ferramentas adiadas (deferred tools):

1. Abra o Agent Builder e adicione ferramentas MCP
2. Clique no menu suspenso em qualquer ferramenta MCP
3. Alternar "Adiar Carregamento" — ferramentas adiadas exibem um ícone de relógio

Nota: A funcionalidade deferred_tools está habilitada por padrão. Ela pode ser alternada através da configuração de agentes no librechat.yaml.

Programmatic Tool Calling

O Programmatic Tool Calling (PTC) permite que agentes executem ferramentas MCP selecionadas de dentro do sandbox do Code Interpreter em vez de chamar cada ferramenta diretamente do modelo. O modelo recebe uma ferramenta de orquestração baseada no Code Interpreter, escreve código em sandbox que chama funções de ferramenta geradas e pode usar loops, condicionais, novas tentativas e processamento de resultados antes de retornar uma resposta.

Isso é útil para fluxos de trabalho de ferramentas com várias etapas, como consultar diversos recursos, paginar resultados, comparar saídas ou transformar respostas de ferramentas antes que o agente as explique.

Configurando ferramentas programáticas:

1. Enable both programmatic_tools and execute_code in the librechat.yaml agents capabilities.
2. Habilite o Code Interpreter no agente.
3. Adicione ferramentas MCP, expanda um servidor MCP e alterne Programmatic para ferramentas individuais ou para o servidor completo. Ferramentas Programmatic exibem um ícone de código.

Nota: programmatic_tools é opcional e não está incluído na lista de capacidades padrão dos agentes. O PTC também requer uma implementação do Code Interpreter com o componente Tool Call Server. Apenas ferramentas registradas para o agente podem ser chamadas a partir do sandbox; chamadas de ferramentas não registradas são rejeitadas.

Skills

Skills permitem que agentes carreguem instruções reutilizáveis a partir de definições em SKILL.md. Elas podem ser selecionadas manualmente no chat com $, descobertas automaticamente pelo modelo através do catálogo de skills ou sempre aplicadas a cada turno.

Para detalhes sobre autoria, invocação e controle de acesso, consulte Skills.

Artifacts

A funcionalidade de Artifacts permite que seu agente gere e exiba conteúdo interativo:

• Crie componentes React, código HTML e diagramas Mermaid
• Exibir conteúdo em uma janela de interface separada para maior clareza e interação
• Configure instruções específicas para artefatos no nível do agente
• Mais informações sobre Artifacts

Quando ativado, instruções adicionais específicas para o uso de artefatos são adicionadas por padrão. As opções incluem:

• Habilitar instruções do shadcn/ui: Adiciona instruções para usar componentes do shadcn/ui (uma coleção de componentes reutilizáveis construídos usando Radix UI e Tailwind CSS)
• Modo de Prompt Personalizado: Quando ativado, o prompt do sistema de artefatos padrão não será incluído, permitindo que você forneça suas próprias instruções personalizadas

Configurar artifacts no nível do agente é a abordagem preferida, pois permite um controle mais granular em comparação com a configuração legada de todo o aplicativo.

Se você habilitar o Custom Prompt Mode, você deve incluir, no mínimo, o formato básico de artefato em suas instruções.

Aqui está um exemplo simples das instruções mínimas necessárias:

When creating content that should be displayed as an artifact, use the following format:

:::artifact{identifier="unique-identifier" type="mime-type" title="Artifact Title"}

```
Your artifact content here
```

:::

For the type attribute, use one of:

- "text/html" for HTML content
- "application/vnd.mermaid" for Mermaid diagrams
- "application/vnd.react" for React components
- "image/svg+xml" for SVG images

Ferramentas

Os Agents também podem ser aprimorados com várias ferramentas integradas:

• Ferramentas de Imagem da OpenAI: Geração e edição de imagens usando GPT-Image-1
• Gemini Image Tools: Geração de imagens e edição com contexto de imagem usando modelos de imagem do Gemini
• DALL-E-3: Geração de imagens a partir de descrições de texto
• Stable Diffusion / Flux: Geração de texto para imagem
• Wolfram: Recursos computacionais e matemáticos
• OpenWeather: Recuperação de dados meteorológicos
• Google Search: Acesso à funcionalidade de pesquisa na web
• Calculator: Cálculos matemáticos
• Tavily Search: API de pesquisa avançada com integração de diversas fontes de dados
• Azure AI Search: Recuperação de informações de índices do Azure AI Search
• Traversaal: Uma API de busca robusta para Agentes de LLM

Criar um Agente com Ferramentas de Imagem

1. Adicione as credenciais da ferramenta de imagem ao .env, como IMAGE_GEN_OAI_API_KEY para as ferramentas de imagem da OpenAI.
2. Reinicie o LibreChat para que as novas variáveis de ambiente sejam carregadas.
3. Selecione Agents no menu de endpoint.
4. Abra o Agent Builder no painel lateral e crie ou edite um agente.
5. Abra a lista de Tools do agente, selecione OpenAI Image Tools, Gemini Image Tools, DALL-E-3, Stable Diffusion ou Flux e, em seguida, salve o agente.
6. Inicie um chat com esse agente e peça para ele gerar ou editar uma imagem.

Para o guia completo de configuração de imagens, incluindo variáveis de modelo como IMAGE_GEN_OAI_MODEL, consulte Geração e Edição de Imagens.

• As ferramentas podem ser desativadas usando o arquivo de configuração librechat.yaml:
  • Mais informações

Actions

Com a funcionalidade Actions, você pode criar ferramentas dinamicamente a partir de OpenAPI specs para adicionar aos seus Agents.

Clicar no botão acima abrirá um formulário onde você pode inserir a URL da especificação OpenAPI e criar uma action:

• As Actions podem ser desabilitadas usando o arquivo de configuração librechat.yaml:
  • Mais informações
• Domínios individuais podem ser incluídos na lista de permissões para ações de agentes:
  • Mais informações
• Observe que você pode adicionar a flag 'x-strict': true no nível da operação na especificação OpenAPI para actions. Se estiver usando um modelo OpenAI que suporte isso, isso gerará automaticamente chamadas de função com o modo 'strict' ativado.
  • O modo estrito suporta apenas um subconjunto parcial de json. Leia https://platform.openai.com/docs/guides/structured-outputs para obter detalhes.

Cadeia de Agentes

A funcionalidade Agent Chain permite uma abordagem de Mixture-of-Agents (MoA), permitindo que você crie uma sequência de agentes que trabalham em conjunto:

• Crie cadeias de agentes especializados para tarefas complexas
• Cada agente na cadeia pode acessar as saídas de agentes anteriores
• Configure o número máximo de passos para a cadeia do agente
• Nota: Acesse este recurso no painel de Configurações Avançadas no Agent Builder
• Nota: Este recurso está atualmente em beta e pode estar sujeito a alterações
  • O máximo atual de agentes que podem ser encadeados é 10, mas isso poderá ser configurável no futuro.

Este recurso introduz uma arquitetura de Mixture-of-Agents em camadas ao LibreChat, onde cada agente utiliza todas as saídas dos agentes da camada anterior como informação auxiliar para gerar sua resposta, conforme descrito no artigo homônimo "Mixture-of-Agents".

Subagentes

Subagents permitem que um agente delegue uma tarefa específica para uma execução filha isolada. O filho obtém sua própria janela de contexto e fluxo de execução de ferramentas, retornando então um resultado compacto para o pai, em vez de preencher o contexto do pai com cada etapa intermediária.

Subagents são diferentes de Agent Chain: o chain runs coordena múltiplos agentes como participantes de um grafo, enquanto subagents são gerados por um agente como uma chamada de ferramenta para delegação de escopo. Para configuração e limites, veja Subagents.

Configurações Avançadas

Configurações avançadas para seu agente (encontradas na visualização Advanced do formulário de Agent) fora de "capabilities."

Max Agent Steps

Esta configuração permite limitar o número de passos que um agente pode realizar em uma "execução" (run), o que se refere ao loop do agente antes que uma resposta final seja fornecida.

Se deixado sem configuração, o padrão é 25 passos, mas você pode ajustar isso para atender às suas necessidades. Para administradores, é possível definir um padrão global, bem como um máximo global no arquivo librechat.yaml.

Um "step" refere-se a uma requisição de API de IA ou a uma rodada de uso de ferramentas (1 ou várias ferramentas, dependendo de quantas chamadas de ferramenta o LLM fornecer a partir de uma única requisição).

Uma resposta única, sem ferramentas, é 1 passo. Uma rodada singular de uso de ferramentas geralmente consiste em 3 passos:

1. Requisição de API -> 2. Uso de Ferramentas (1 ou muitas ferramentas) -> 3. Requisição de API de Acompanhamento

Gerenciamento de Arquivos

Os Agents suportam várias maneiras de trabalhar com arquivos:

Na Interface de Chat

Ao conversar com um agente, você tem quatro opções de upload:

1. Fazer upload de imagens

   • Faz upload de imagens para suporte nativo a modelos de visão
   • Envia imagens diretamente para o provedor do modelo

2. Upload como Texto (requer a capacidade context)

   • Extrai e inclui o conteúdo completo do documento na conversa
   • Usa análise de texto por padrão; aprimorado por OCR se configurado
   • O conteúdo existe apenas na conversa atual
   • Veja Upload as Text

3. Upload para File Search (requer a capacidade file_search, ativada)

   • Usa busca semântica (RAG) com armazenamentos de vetores
   • Retorna blocos relevantes via uso de ferramentas
   • Ideal para documentos grandes/múltiplos arquivos
   • Sub-ótimo para dados estruturados (CSV, Excel, JSON, etc.)

4. Upload para Code Interpreter (requer a funcionalidade execute_code, ativada)

   • Adiciona arquivos ao ambiente do interpretador de código
   • Ideal para dados estruturados (CSV, Excel, JSON, etc.)
   • Mais informações sobre o Code Interpreter

No Agent Builder

Ao configurar um agente, você pode anexar arquivos em diferentes categorias:

1. Upload de Imagem: Para conteúdo visual que o agente pode referenciar
2. Upload de Pesquisa de Arquivos: Documentos para capacidades de RAG
3. Code Interpreter Upload: Arquivos para processamento de código
4. Contexto de Arquivo: Documentos com texto extraído para complementar as instruções do agente

File Context usa a capacidade context e funciona exatamente como "Upload as Text" - ele usa análise de texto por padrão e é aprimorado por OCR quando configurado. O texto é extraído no momento do upload e armazenado nas instruções do agente. Isso é ideal para fornecer aos agentes conhecimento persistente a partir de documentos, PDFs, arquivos de código ou imagens com texto.

Prioridade de processamento: OCR > STT > análise de texto (o mesmo que Upload como Texto)

Nota: O texto extraído é incluído como parte das instruções de sistema do agente.

Compartilhamento e Permissões

Os Agents utilizam o sistema granular de controle de acesso do LibreChat. Cada agent possui sua própria Lista de Controle de Acesso (ACL) e pode ser compartilhado com usuários, grupos, funções específicos ou publicamente, cada um em um nível de permissão escolhido.

Funções de Acesso

Ao compartilhar um agente, é atribuída ao beneficiário uma de três funções:

O autor original e os administradores sempre mantêm controle total, independentemente da ACL.

Compartilhando um Agent

1. Abra o agente no Agent Builder
2. Clique no botão Share no rodapé (visível quando você é o autor, um administrador ou recebeu a permissão SHARE naquele agente específico)
3. Pesquise por usuários, grupos ou funções no seletor de pessoas e atribua uma função a cada um
4. Opcionalmente, alterne Public para tornar o agente visível para todos na instância (requer a permissão de recurso SHARE_PUBLIC)

Para detalhes completos sobre principais, bits de permissão e como ACLs se compõem com permissões de recursos baseadas em funções, veja Access Control.

Controles do Administrador

Os administradores têm acesso às configurações globais de permissão dentro da interface do usuário do construtor de agentes:

• Habilitar/desabilitar o compartilhamento de agentes para todos os usuários
• Controlar permissões de uso de agentes
• Gerenciar direitos de criação de agentes
• Configure as definições de toda a plataforma

A primeira conta criada para sua instância é um administrador. Se você precisar adicionar um administrador adicional, você pode acessar o MongoDB e atualizar o perfil do usuário:

db.users.updateOne(
  { email: 'USER_EMAIL_ADDRESS' },
  { $set: { role: 'ADMIN' } }
)

O uso de agentes para todos os usuários também pode ser desativado via configuração, mais informações.

As permissões em nível de recurso (quem pode usar, criar, compartilhar ou compartilhar publicamente agentes) são gerenciadas a partir do Painel de Administração do LibreChat em cada função, incluindo quaisquer funções personalizadas. O bloco interface.agents no librechat.yaml ainda pode definir padrões para a função USER integrada na inicialização, mas o painel de administração é a forma recomendada para editá-los daqui em diante.

Compartilhamento em Nível de Usuário

Usuários individuais podem:

• Compartilhe seus agentes com usuários, grupos ou funções específicos (se SHARE estiver habilitado para a função deles)
• Tornar os agentes visíveis para todos na instância (se SHARE_PUBLIC estiver habilitado)
• Conceda a cada destinatário um nível de acesso diferente (Visualizador / Editor / Proprietário)
• Compartilhe novamente ou revogue o acesso a qualquer momento a partir da caixa de diálogo de compartilhamento

Notas

• Instruções, parâmetros de modelo, arquivos anexados e ferramentas só são expostos ao usuário se ele tiver permissões de edição.
  • Um agente pode vazar quaisquer dados anexados, sejam instruções ou arquivos, através da conversa, portanto, certifique-se de que suas instruções sejam robustas contra isso antes de conceder acesso de Editor/Proprietário ou tornar o agente público.
• Apenas autores originais, administradores e beneficiários com permissão de Owner podem excluir agentes compartilhados
• Agentes são privados para os autores, a menos que sejam compartilhados

Configuração Opcional

O LibreChat permite que administradores configurem o uso de agentes através do arquivo librechat.yaml:

• Desativar Agents para todos os usuários (incluindo administradores): mais informações
• Personalize as capacidades do agente usando: mais informações

Melhores Práticas

• Forneça instruções claras e específicas para o seu agente
• Considere cuidadosamente quais ferramentas são necessárias para o seu caso de uso
• Organize os arquivos adequadamente entre as quatro categorias de upload
• Revise as configurações de permissão antes de compartilhar agentes
• Teste seu agente minuciosamente antes de disponibilizá-lo para outros usuários

Recapitulação

1. Selecione "Agents" no menu suspenso de endpoint
2. Abra o painel do Agent Builder
3. Preencha os detalhes necessários do agente
4. Configure as capacidades desejadas (Code Interpreter, File Search, File Context, etc.)
5. Adicione as ferramentas e arquivos necessários
6. Defina as permissões de compartilhamento, se desejar
7. Crie e comece a usar seu agente

Ao conversar com agentes, você pode:

• Use "Upload as Text" para incluir o conteúdo completo do documento nas conversas (análise de texto por padrão, aprimorada por OCR)
• Use "Upload for File Search" para busca semântica em documentos (requer RAG API)
• Adicione arquivos ao "File Context" do agente para incluir o conteúdo completo de um arquivo como parte das instruções de sistema do agente.

Migração Necessária (v0.8.0-rc3+)

O que a migração faz

A migração de permissões de agentes transita seus agentes de um modelo simples de propriedade para um sistema sofisticado baseado em ACL com múltiplos níveis de permissão:

• OWNER: Controle total sobre o agente
• EDITOR: Pode visualizar e modificar o agente
• VIEWER: Acesso somente leitura ao agente

Sem executar esta migração, os agentes existentes ficarão inacessíveis através dos novos endpoints da API com reconhecimento de permissões.

Executando a Migração

Escolha o comando apropriado com base no seu método de implantação:

1. Para o docker-compose.yml padrão (se você usa docker compose up para iniciar o aplicativo):

Visualizar alterações (dry run):

docker compose exec api npm run migrate:agent-permissions:dry-run

Executar migração:

docker compose exec api npm run migrate:agent-permissions

Tamanho de lote personalizado (para grandes conjuntos de dados):

docker compose exec api npm run migrate:agent-permissions:batch

2. Para o deploy-compose.yml

Se você seguiu o Ubuntu Docker Guide:

Visualizar alterações (dry run):

docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run migrate:agent-permissions:dry-run"

Executar migração:

docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run migrate:agent-permissions"

Tamanho de lote personalizado (para grandes conjuntos de dados):

docker exec -it LibreChat-API /bin/sh -c "cd .. && npm run migrate:agent-permissions:batch"

3. Para desenvolvimento local (a partir da raiz do projeto):

Visualizar alterações (dry run):

npm run migrate:agent-permissions:dry-run

Executar migração:

npm run migrate:agent-permissions

Tamanho de lote personalizado (para grandes conjuntos de dados):

npm run migrate:agent-permissions:batch

O que acontece durante a migração

• Agentes Privados: Permanecem acessíveis apenas aos seus criadores (recebem permissão de OWNER)
• Agentes Compartilhados: Se um agente foi compartilhado anteriormente, ele receberá entradas de ACL apropriadas como um Agente Público (compartilhado com todos os usuários)
• Detecção do Sistema: O LibreChat detecta automaticamente agentes não migrados na inicialização e exibe um aviso

Você pode ajustar as permissões do agente resultante através da interface do Agent Builder.

Agents API (Beta)

Agentes do LibreChat também podem ser acessados programaticamente via API, permitindo que aplicações externas e scripts interajam com seus agentes usando SDKs compatíveis com OpenAI ou o formato Open Responses.

Veja a documentação da Agents API para detalhes de configuração e uso.

O que vem a seguir?

Os Agents do LibreChat inauguram uma nova era para o aplicativo, onde pipelines futuros podem ser otimizados por meio de Agents para tarefas e fluxos de trabalho específicos em toda a sua experiência no LibreChat.

Atualizações futuras incluirão:

• Melhorias gerais na experiência atual de Agentes
• Orquestração multi-agente para fluxos de trabalho complexos
• Capacidade de personalizar agentes para várias funções: titulação (nomeação de tópicos de chat), gerenciamento de memória (contexto/histórico do usuário) e aprimoramento de prompts (assistência/previsões de entrada)
• Mais ferramentas, parâmetros de ferramenta configuráveis, criação dinâmica de ferramentas.

Além disso, a atualização introduz um novo paradigma para o LibreChat, já que sua arquitetura subjacente proporciona uma renovação muito necessária para o aplicativo, otimizando tanto a experiência do usuário quanto o desempenho geral do aplicativo.

Para destacar uma otimização notável, uma geração de IA de aproximadamente 1000 tokens transferirá cerca de 1 MB de dados usando endpoints tradicionais (no momento em que este artigo foi escrito, qualquer opção de endpoint além de Agents e AWS Bedrock).

Ao usar um agente, a mesma geração transferirá cerca de 52 kb de dados, uma redução de 95% na transferência de dados, o que representa uma carga muito menor no servidor e no dispositivo do usuário.

Agentes de IA no LibreChat oferecem uma maneira poderosa de criar assistentes especializados sem conhecimento em programação, mantendo a flexibilidade para trabalhar com seus modelos e provedores de IA preferidos.

#LibreChat #AIAssistants #NoCode #OpenSource