Criar Plugin para Agent: Guia Rápido com Exemplos Práticos

Introdução aos Plugins do Agente

O campo da inteligência artificial está evoluindo rapidamente, com modelos de linguagem de grande escala (LLMs) na vanguarda dessa revolução. Estes modelos, embora poderosos, muitas vezes operam dentro dos limites dos dados de treinamento. Para realmente liberar seu potencial e integrá-los em aplicações do mundo real, precisamos expandir suas capacidades além da simples geração de texto. É aqui que os plugins do agente entram em cena. Os plugins do agente são essencialmente ferramentas ou funções que um agente de IA pode decidir usar para executar tarefas específicas, acessar informações externas ou interagir com outros sistemas. Eles reduzem a lacuna entre as capacidades de raciocínio do LLM e o mundo exterior, transformando um modelo de linguagem em um agente sofisticado e orientado a objetivos.

Imagine um assistente de IA que entende não apenas seu pedido de ‘encontrar o restaurante italiano mais próximo’, mas que pode realmente navegar na web, filtrar resultados e fornecer direções. Esse nível de funcionalidade é alcançado graças aos plugins. Esses plugins permitem que o agente:

• Acesse Dados em Tempo Real: Recupere o clima atual, preços de ações, notícias ou informações de um banco de dados.
• Realize Ações: Envie e-mails, agende compromissos, controle dispositivos domésticos inteligentes ou interaja com APIs.
• Supere as Limitações dos LLM: Realize cálculos complexos, execute código ou recupere informações factuais precisas que podem ultrapassar os limites de seus dados de treinamento.

Este guia o levará através dos passos práticos para a criação de plugins do agente, com foco em uma abordagem de início rápido com exemplos claros para você começar.

Compreendendo os Conceitos Chave

Como os Agentes Usam os Plugins

No centro de tudo isso, um agente de IA opera em um ciclo de ‘refletir-planejar-agir’. Quando recebe um chamado, o agente ‘reflete’ primeiro sobre a melhor linha de ação. Se determinar que é necessário uma ferramenta externa (plugin) para atender ao pedido, ‘planeja’ qual plugin utilizar, quais argumentos passar e então ‘age’ invocando esse plugin. A saída do plugin é então retornada ao agente, que utiliza essas novas informações para continuar seu processo de raciocínio e formular uma resposta final.

Componentes Chave de um Plugin

Embora as implementações possam variar, a maioria dos plugins do agente compartilha estes componentes fundamentais:

• Nome: Um identificador único para o plugin (por exemplo, get_weather, send_email).
• Descrição: Uma explicação concisa do que o plugin faz. Isso é crucial, pois o LLM utiliza essa descrição para decidir quando e como usar o plugin.
• Parâmetros/Esquema: Uma definição das entradas que o plugin espera, frequentemente descrita utilizando um esquema (como JSON Schema). Isso indica ao LLM quais argumentos fornecer.
• Função/Implementação: O código real que executa a lógica do plugin (por exemplo, fazer uma chamada API, executar um cálculo).

Início Rápido: Crie Seu Primeiro Plugin

Para este início rápido, usaremos um framework baseado em Python que simplifica o desenvolvimento de agentes. Muitos frameworks como LangChain, LlamaIndex, ou mesmo as capacidades de chamada de função da OpenAI fornecem mecanismos semelhantes. Focaremos nos princípios que são transferíveis entre eles.

Requisitos Preliminares

• Python instalado (3.8+)
• Um ambiente virtual (recomendado)
• Um entendimento básico das funções Python

Exemplo 1: Um Plugin de Calculadora Simples

Vamos começar com um plugin muito básico que realiza adição. Embora um LLM possa fazer operações matemáticas simples, isso ilustra claramente o processo.

Passo 1: Definindo a Função do Plugin

Primeiro, vamos criar uma função Python padrão que executa a operação desejada.

# calculator_plugin.py
def add_numbers(num1: float, num2: float) -> float:
 """
 Adiciona dois números juntos.
 Args:
 num1 (float): O primeiro número.
 num2 (float): O segundo número.
 Returns:
 float: A soma dos dois números.
 """
 return num1 + num2

Passo 2: Descrever o Plugin para o Agente

É aqui que os frameworks são úteis. Eles fornecem decoradores ou classes específicas para transformar uma função Python comum em uma ferramenta acessível por um agente. Precisamos fornecer uma descrição e, implicitamente, o LLM inferirá os parâmetros da assinatura da função e das docstrings.

Utilizamos uma representação conceitual do framework (semelhante a como LangChain ou LlamaIndex a abstrairiam) :

# Utilizando uma classe 'Tool' conceitual (semelhante ao instrumento de LangChain ou à FunctionTool de LlamaIndex)
class CalculatorTool:
 def __init__(self):
 self.name = "add_numbers"
 self.description = (
 "Uma ferramenta para adicionar dois números. "
 "Útil quando você precisa somar dois valores numéricos."
 )
 self.function = add_numbers
 self.parameters = {
 "type": "object",
 "properties": {
 "num1": {"type": "number", "description": "O primeiro número a ser adicionado"},
 "num2": {"type": "number", "description": "O segundo número a ser adicionado"}
 },
 "required": ["num1", "num2"]
 }

# Ou, mais praticamente, utilizando a criação de ferramentas integrada de um framework :

# Exemplo com a criação de ferramenta de função de LangChain
from langchain.tools import create_function_tool

def add_numbers(num1: float, num2: float) -> float:
 """
 Adiciona dois números juntos.
 Args:
 num1 (float): O primeiro número.
 num2 (float): O segundo número.
 Returns:
 float: A soma dos dois números.
 """
 return num1 + num2

add_tool = create_function_tool(
 func=add_numbers,
 name="add_numbers",
 description="Uma ferramenta para adicionar dois números. Útil quando você precisa somar dois valores numéricos."
)

print(add_tool.name)
print(add_tool.description)
# print(add_tool.args) # LangChain infere isso da assinatura da função

A description é fundamental. O LLM se baseia consideravelmente nisso para entender o objetivo do plugin e quando invocá-lo. Tornar tudo isso claro, conciso e destacar sua utilidade.

Passo 3 : Integrar com um Agente

Agora precisamos fornecer essa ferramenta a um agente IA. Isso geralmente envolve a instância de um LLM e de uma classe de agente, então passamos nossa lista de ferramentas a este último.

Utilizando LangChain como exemplo :

from langchain_openai import ChatOpenAI
from langchain.agents import AgentExecutor, create_openai_tools_agent
from langchain import hub

# Supondo que você tenha uma chave API OpenAI definida como variável de ambiente (OPENAI_API_KEY)
llm = ChatOpenAI(model="gpt-4o", temperature=0)

# As ferramentas que criamos
tools = [add_tool]

# Recuperar o convite do hub de LangChain
prompt = hub.pull("hwchase17/openai-tools-agent")

# Criar o agente
agent = create_openai_tools_agent(llm, tools, prompt)

# Criar um executor de agente para fazer o agente funcionar
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# Agora, vamos fazer isso funcionar!
response = agent_executor.invoke({"input": "Qual é a soma de 123 e 456?"})
print(response["output"])

Quando você executar isso, verá o processo de reflexão do agente (se verbose=True) :

> Entrou em uma nova cadeia de execução de AgentExecutor...
Pensamento :
O usuário está pedindo para somar dois números. A ferramenta `add_numbers` é apropriada para essa tarefa.
Devo chamar a ferramenta `add_numbers` com `num1=123` e `num2=456`.
Ação :
```json
{
 "tool_name": "add_numbers",
 "args": {
 "num1": 123,
 "num2": 456
 }
}
```
Observação : 579.0
Pensamento :
A ferramenta `add_numbers` retornou 579.0. Esta é a soma de 123 e 456.
Devo agora responder ao usuário com o resultado.
Resposta Final : A soma de 123 e 456 é 579.0.

> Cadeia encerrada.
A soma de 123 e 456 é 579.0.

Exemplo Prático 2 : Um Plugin Meteorológico

Vamos construir um plugin mais prático que recupera as informações meteorológicas atuais utilizando uma API pública. Usaremos a API OpenWeatherMap para este exemplo (você precisará de uma chave API gratuita).

Passo 1 : Obter uma Chave API

Vá para a API OpenWeatherMap e registre-se para obter uma chave API gratuita.

Passo 2 : Definir a Função do Plugin

Esta função fará uma solicitação HTTP para a API OpenWeatherMap.

“`html

import requests
import os
from typing import Dict, Any

# Certifique-se de definir sua chave API como variável de ambiente
# Por exemplo, export OPENWEATHER_API_KEY="YOUR_API_KEY"
OPENWEATHER_API_KEY = os.getenv("OPENWEATHER_API_KEY")

def get_current_weather(city: str, unit: str = "metric") -> Dict[str, Any]:
 """
 Recupera as condições meteorológicas atuais para uma cidade especificada.

 Args:
 city (str): O nome da cidade (por exemplo, "Londres", "Nova York").
 unit (str): A unidade de temperatura. Pode ser "metric" (Celsius) ou "imperial" (Fahrenheit). Por padrão "metric".

 Returns:
 dict: Um dicionário contendo informações meteorológicas, ou uma mensagem de erro.
 """
 if not OPENWEATHER_API_KEY:
 return {"error": "Chave API OpenWeatherMap não definida."}

 base_url = "http://api.openweathermap.org/data/2.5/weather"
 params = {
 "q": city,
 "appid": OPENWEATHER_API_KEY,
 "units": unit
 }
 try:
 response = requests.get(base_url, params=params)
 response.raise_for_status() # Levanta um HTTPError para respostas erradas (4xx ou 5xx)
 data = response.json()

 if data.get("cod") == "404":
 return {"error": f"Cidade '{city}' não encontrada."}

 weather_description = data["weather"][0]["description"]
 temperature = data["main"]["temp"]
 feels_like = data["main"]["feels_like"]
 humidity = data["main"]["humidity"]
 wind_speed = data["wind"]["speed"]

 return {
 "city": city,
 "description": weather_description,
 "temperature": temperature,
 "feels_like": feels_like,
 "humidity": humidity,
 "wind_speed": wind_speed,
 "unit": "Celsius" if unit == "metric" else "Fahrenheit"
 }
 except requests.exceptions.RequestException as e:
 return {"error": f"Erro de rede ou API: {e}"}
 except KeyError as e:
 return {"error": f"Erro ao analisar os dados meteorológicos: chave ausente {e}. Resposta: {data}"}

Passo 3: Criar a ferramenta para o agente

from langchain.tools import create_function_tool

weather_tool = create_function_tool(
 func=get_current_weather,
 name="get_current_weather",
 description=(
 "Uma ferramenta para recuperar as condições meteorológicas atuais para uma cidade especificada. "
 "Útil quando a previsão do tempo atual, a temperatura ou as condições em um local são solicitadas. "
 "Forneça o nome da cidade e, opcionalmente, a unidade (métrica para Celsius, imperial para Fahrenheit)."
 )
)

print(weather_tool.name)
print(weather_tool.description)

Note a descrição detalhada, que ajuda o LLM a entender quando usar esta ferramenta e quais parâmetros requer.

Passo 4: Integrar e Testar

Adicione a nova ferramenta à lista de ferramentas do seu agente e teste-a.

# ... (importações anteriores e configuração do LLM)

# Combinar nossas ferramentas
tools = [add_tool, weather_tool]

# Criar o agente e o executor como antes
agent = create_openai_tools_agent(llm, tools, prompt)
agent_executor = AgentExecutor(agent=agent, tools=tools, verbose=True)

# Testar o plugin meteorológico
response_weather = agent_executor.invoke({"input": "Como está o tempo em Tóquio?"})
print(response_weather["output"])

response_weather_imperial = agent_executor.invoke({"input": "Qual é a temperatura em Nova York em Fahrenheit?"})
print(response_weather_imperial["output"])

response_invalid_city = agent_executor.invoke({"input": "Me diga como está o tempo em Nocityhere."})
print(response_invalid_city["output"])

Resultado esperado (variável de acordo com o clima real e a configuração da chave API):

> Entrou em uma nova string AgentExecutor...
Reflexão:
O usuário pede a previsão do tempo em Tóquio. A ferramenta `get_current_weather` é apropriada para essa tarefa.
Devo chamar `get_current_weather` com `city='Tóquio'`.
Ação:
```json
{
 "tool_name": "get_current_weather",
 "args": {
 "city": "Tóquio"
 }
}
```
Observação: {'city': 'Tóquio', 'description': 'chuva leve', 'temperature': 15.2, 'feels_like': 14.8, 'humidity': 90, 'wind_speed': 3.09, 'unit': 'Celsius'}
Reflexão:
A previsão do tempo em Tóquio é uma chuva leve com uma temperatura de 15.2 Celsius, percebida como 14.8 Celsius. A umidade é de 90% e a velocidade do vento é de 3.09 m/s.
Resposta final: Em Tóquio, a previsão atual do tempo é uma chuva leve, com uma temperatura de 15.2°C (percebida como 14.8°C). A umidade é de 90% e a velocidade do vento é de 3.09 m/s.
> Stringa terminada.
Em Tóquio, a previsão atual do tempo é uma chuva leve, com uma temperatura de 15.2°C (percebida como 14.8°C). A umidade é de 90% e a velocidade do vento é de 3.09 m/s.

Considerações Avançadas e Melhores Práticas

Gerenciamento de Erros

“`

Como visto no exemplo de clima, os plugins no mundo real interagem com sistemas externos que podem falhar. Sempre implemente uma gestão de erros robusta (blocos try-except) para capturar problemas de rede, erros de API ou formatos de dados imprevistos. Retorne mensagens de erro informativas para que o agente possa entender o que deu errado e, eventualmente, comunicar isso ao usuário ou tentar uma abordagem alternativa.

Descrições Claras e Específicas

Isso não pode ser subestimado. A capacidade do LLM de escolher a ferramenta correta depende quase inteiramente da qualidade da descrição do seu plugin. Inclua:

• O que a ferramenta faz.
• Quando deve ser utilizada.
• Quais parâmetros são esperados e seus tipos/propósitos.
• Todas as restrições ou efeitos colaterais.

Validação de Parâmetros

Embora o LLM tente inferir os parâmetros, é útil praticar a validação das entradas dentro das suas funções de plugin. Isso impede que dados imprevistos causem problemas se o LLM cometer um erro ou se o usuário fornecer uma entrada malformada.

Operações Assíncronas

Para plugins que envolvem operações de longa duração (por exemplo, consultas complexas em um banco de dados, downloads de arquivos grandes), considere implementá-los de forma assíncrona para evitar bloquear a thread de execução do agente. Muitos frameworks suportam ferramentas assíncronas.

Gestão de Estado (Avançado)

A maior parte dos plugins simples é sem estado. No entanto, para interações mais complexas, um agente pode precisar manter um estado ao longo de vários turnos ou chamadas de plugins. Este é um tópico mais avançado e frequentemente envolve que o framework do agente gerencie o histórico da conversa ou uma memória de estado dedicada.

Segurança

Preste atenção à segurança ao expor funcionalidades por meio de plugins. Um agente pode ser potencialmente induzido a abusar de um plugin se não estiver adequadamente protegido. Considere:

• Controle de Acesso: Certifique-se de que os plugins acessem apenas os recursos para os quais estão autorizados.
• Sanitização de Entradas: Previna ataques de injeção se as entradas do plugin forem passadas para bancos de dados ou comandos shell.
• Mínimo Privilégio: Forneça aos plugins apenas as permissões mínimas necessárias para realizar sua tarefa.

Cadeia de Ferramentas e Raciocínio

O verdadeiro poder dos agentes surge quando podem encadear várias ferramentas juntas. Por exemplo, um agente pode primeiro usar uma ferramenta de ‘pesquisa’ para encontrar informações relevantes, depois uma ferramenta de ‘síntese’ para destilar essas informações e, finalmente, uma ferramenta ‘email’ para enviar o resumo. Projete seus plugins para serem atômicos e componíveis, permitindo que o agente os combine de forma flexível.

Conclusão

Construir plugins para agentes é uma forma poderosa de estender as capacidades dos grandes modelos de linguagem, transformando-os de geradores de texto sofisticados em agentes inteligentes e orientados à ação. Seguindo este guia de iniciação rápida e compreendendo os princípios fundamentais, você pode começar a integrar dados externos, serviços e lógicas complexas em suas aplicações de IA.

Não se esqueça de focar em descrições claras, uma gestão de erros robusta e projetar funções atômicas e componíveis. À medida que você se sentir mais confortável, poderá explorar tópicos mais avançados como operações assíncronas, gestão de estado e segurança para construir agentes de IA cada vez mais sofisticados e confiáveis. O futuro da interação com a IA reside nessas capacidades expandidas, e ao dominar o desenvolvimento de plugins, você está na vanguarda dessa emocionante fronteira.

🕒 Published: April 5, 2026