ai-agents-for-beginners

Como Projetar Bons Agentes de IA

(Clique na imagem acima para assistir ao vídeo desta lição)

Padrão de Design de Uso de Ferramentas

Ferramentas são interessantes porque permitem que agentes de IA tenham um conjunto mais amplo de capacidades. Em vez de o agente ter um conjunto limitado de ações que pode executar, ao adicionar uma ferramenta, o agente pode agora realizar uma ampla gama de ações. Neste capítulo, veremos o Padrão de Design de Uso de Ferramentas, que descreve como agentes de IA podem usar ferramentas específicas para alcançar seus objetivos.

Introdução

Nesta lição, buscamos responder às seguintes perguntas:

Objetivos de Aprendizagem

Após completar esta lição, você será capaz de:

O que é o Padrão de Design de Uso de Ferramentas?

O Padrão de Design de Uso de Ferramentas foca em dar aos LLMs a capacidade de interagir com ferramentas externas para alcançar objetivos específicos. Ferramentas são códigos que podem ser executados por um agente para realizar ações. Uma ferramenta pode ser uma função simples como uma calculadora, ou uma chamada de API para um serviço terceirizado como consulta de preço de ações ou previsão do tempo. No contexto de agentes de IA, ferramentas são projetadas para serem executadas por agentes em resposta a chamadas de função geradas pelo modelo.

Quais são os casos de uso aos quais ele pode ser aplicado?

Agentes de IA podem alavancar ferramentas para completar tarefas complexas, recuperar informações ou tomar decisões. O padrão de design de uso de ferramentas é frequentemente usado em cenários que exigem interação dinâmica com sistemas externos, como bancos de dados, serviços web ou interpretadores de código. Essa habilidade é útil para vários casos de uso, incluindo:

Quais são os elementos/blocos de construção necessários para implementar o padrão de design de uso de ferramentas?

Esses blocos de construção permitem que o agente de IA realize uma ampla variedade de tarefas. Vamos ver os principais elementos necessários para implementar o Padrão de Design de Uso de Ferramentas:

A seguir, vamos analisar o Chamamento de Função/Ferramenta em mais detalhes.

Chamamento de Função/Ferramenta

Chamamento de função é a principal forma que habilita os Modelos de Linguagem Grandes (LLMs) a interagir com ferramentas. Frequentemente você verá ‘Função’ e ‘Ferramenta’ usados de forma intercambiável porque ‘funções’ (blocos de código reutilizável) são as ‘ferramentas’ que agentes usam para realizar tarefas. Para que o código de uma função seja invocado, um LLM deve comparar o pedido do usuário com a descrição das funções. Para isso, um esquema contendo as descrições de todas as funções disponíveis é enviado ao LLM. O LLM então seleciona a função mais apropriada para a tarefa e retorna seu nome e argumentos. A função selecionada é invocada, sua resposta é enviada de volta ao LLM, que usa a informação para responder ao pedido do usuário.

Para desenvolvedores implementarem chamamento de função para agentes, você precisará de:

  1. Um modelo LLM que suporte chamamento de função
  2. Um esquema contendo descrições das funções
  3. O código para cada função descrita

Vamos usar o exemplo de obter a hora atual em uma cidade para ilustrar:

  1. Inicialize um LLM que suporte chamamento de função:

    Nem todos os modelos suportam chamamento de função, então é importante verificar se o LLM que você está usando suporta. Azure OpenAI suporta chamamento de função. Podemos começar iniciando o cliente Azure OpenAI.

     # Inicializar o cliente Azure OpenAI
 client = AzureOpenAI(
     azure_endpoint = os.getenv("AZURE_OPENAI_ENDPOINT"), 
     api_key=os.getenv("AZURE_OPENAI_API_KEY"),  
     api_version="2024-05-01-preview"
 )

  2. Crie um Esquema de Função:

    Em seguida, definiremos um esquema JSON que contém o nome da função, descrição do que a função faz, e os nomes e descrições dos parâmetros da função. Depois pegaremos esse esquema e o passaremos para o cliente criado anteriormente, junto com o pedido do usuário para encontrar a hora em São Francisco. O que é importante notar é que uma chamada de ferramenta é o que é retornado, não a resposta final para a pergunta. Como mencionado anteriormente, o LLM retorna o nome da função que selecionou para a tarefa, e os argumentos que serão passados a ela.

     # Descrição da função para o modelo ler
 tools = [
     {
         "type": "function",
         "function": {
             "name": "get_current_time",
             "description": "Get the current time in a given location",
             "parameters": {
                 "type": "object",
                 "properties": {
                     "location": {
                         "type": "string",
                         "description": "The city name, e.g. San Francisco",
                     },
                 },
                 "required": ["location"],
             },
         }
     }
 ]

      
 # Mensagem inicial do usuário
 messages = [{"role": "user", "content": "What's the current time in San Francisco"}] 
  
 # Primeira chamada da API: Solicitar ao modelo para usar a função
   response = client.chat.completions.create(
       model=deployment_name,
       messages=messages,
       tools=tools,
       tool_choice="auto",
   )
  
   # Processar a resposta do modelo
   response_message = response.choices[0].message
   messages.append(response_message)
  
   print("Model's response:")  

   print(response_message)
  

     Model's response:
 ChatCompletionMessage(content=None, role='assistant', function_call=None, tool_calls=[ChatCompletionMessageToolCall(id='call_pOsKdUlqvdyttYB67MOj434b', function=Function(arguments='{"location":"San Francisco"}', name='get_current_time'), type='function')])

  3. O código da função necessário para realizar a tarefa:

    Agora que o LLM escolheu qual função precisa ser executada, o código que realiza a tarefa precisa ser implementado e executado. Podemos implementar o código para obter a hora atual em Python. Também precisaremos escrever o código para extrair o nome e os argumentos da response_message para obter o resultado final.

       def get_current_time(location):
     """Get the current time for a given location"""
     print(f"get_current_time called with location: {location}")  
     location_lower = location.lower()
        
     for key, timezone in TIMEZONE_DATA.items():
         if key in location_lower:
             print(f"Timezone found for {key}")  
             current_time = datetime.now(ZoneInfo(timezone)).strftime("%I:%M %p")
             return json.dumps({
                 "location": location,
                 "current_time": current_time
             })
      
     print(f"No timezone data found for {location_lower}")  
     return json.dumps({"location": location, "current_time": "unknown"})

      # Lidar com chamadas de função
   if response_message.tool_calls:
       for tool_call in response_message.tool_calls:
           if tool_call.function.name == "get_current_time":
     
               function_args = json.loads(tool_call.function.arguments)
     
               time_response = get_current_time(
                   location=function_args.get("location")
               )
     
               messages.append({
                   "tool_call_id": tool_call.id,
                   "role": "tool",
                   "name": "get_current_time",
                   "content": time_response,
               })
   else:
       print("No tool calls were made by the model.")  
  
   # Segunda chamada de API: Obter a resposta final do modelo
   final_response = client.chat.completions.create(
       model=deployment_name,
       messages=messages,
   )
  
   return final_response.choices[0].message.content

       get_current_time called with location: San Francisco
   Timezone found for san francisco
   The current time in San Francisco is 09:24 AM.

Chamamento de Função está no coração da maioria, senão de todo, o design de uso de ferramentas em agentes, porém implementá-lo do zero pode ser às vezes desafiador. Como aprendemos na Lição 2 frameworks agentivos nos fornecem blocos de construção pré-construídos para implementar o uso de ferramentas.

Exemplos de Uso de Ferramentas com Frameworks Agentivos

Aqui estão alguns exemplos de como você pode implementar o Padrão de Design de Uso de Ferramentas usando diferentes frameworks agentivos:

Semantic Kernel

Semantic Kernel é um framework de IA open-source para desenvolvedores .NET, Python e Java que trabalham com Modelos de Linguagem Grandes (LLMs). Ele simplifica o processo de uso do chamamento de função ao descrever automaticamente suas funções e seus parâmetros para o modelo por meio de um processo chamado serialização. Também gerencia a comunicação de ida e volta entre o modelo e seu código. Outra vantagem de usar um framework agentivo como o Semantic Kernel é que ele permite o acesso a ferramentas pré-construídas como Busca de Arquivos e Interpretador de Código.

O diagrama a seguir ilustra o processo de chamamento de função com Semantic Kernel:

function calling

No Semantic Kernel funções/ferramentas são chamadas Plugins. Podemos converter a função get_current_time que vimos anteriormente em um plugin transformando-a em uma classe que a contenha. Podemos também importar o decorador kernel_function, que recebe a descrição da função. Quando você cria um kernel com o GetCurrentTimePlugin, o kernel automaticamente serializa a função e seus parâmetros, criando o esquema para enviar ao LLM no processo.

from semantic_kernel.functions import kernel_function

class GetCurrentTimePlugin:
    async def __init__(self, location):
        self.location = location

    @kernel_function(
        description="Get the current time for a given location"
    )
    def get_current_time(location: str = ""):
        ...


from semantic_kernel import Kernel

# Criar o kernel
kernel = Kernel()

# Criar o plugin
get_current_time_plugin = GetCurrentTimePlugin(location)

# Adicionar o plugin ao kernel
kernel.add_plugin(get_current_time_plugin)

Azure AI Agent Service

Azure AI Agent Service é um framework agentivo mais recente projetado para capacitar desenvolvedores a construir, implementar e escalar agentes de IA de alta qualidade e extensíveis de forma segura, sem precisar gerenciar os recursos subjacentes de computação e armazenamento. É particularmente útil para aplicações empresariais, pois é um serviço totalmente gerenciado com segurança de nível empresarial.

Quando comparado ao desenvolvimento direto com a API LLM, o Azure AI Agent Service oferece algumas vantagens, incluindo:

As ferramentas disponíveis no Azure AI Agent Service podem ser divididas em duas categorias:

  1. Ferramentas de Conhecimento:
  2. Ferramentas de Ação:

O Agent Service nos permite usar essas ferramentas em conjunto como um conjunto de ferramentas. Ele também utiliza threads que acompanham o histórico de mensagens de uma conversa específica.

Imagine que você é um agente de vendas em uma empresa chamada Contoso. Você quer desenvolver um agente conversacional que possa responder perguntas sobre seus dados de vendas.

A imagem a seguir ilustra como você poderia usar o Azure AI Agent Service para analisar seus dados de vendas:

Agentic Service In Action

Para usar qualquer uma dessas ferramentas com o serviço, podemos criar um cliente e definir uma ferramenta ou conjunto de ferramentas. Para implementar isso na prática, podemos usar o seguinte código Python. O LLM será capaz de olhar para o conjunto de ferramentas e decidir se deve usar a função criada pelo usuário, fetch_sales_data_using_sqlite_query, ou o Interpretador de Código pré-construído dependendo do pedido do usuário.

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from fetch_sales_data_functions import fetch_sales_data_using_sqlite_query # função fetch_sales_data_using_sqlite_query que pode ser encontrada no arquivo fetch_sales_data_functions.py.
from azure.ai.projects.models import ToolSet, FunctionTool, CodeInterpreterTool

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
)

# Inicializar conjunto de ferramentas
toolset = ToolSet()

# Inicializar agente de chamada de função com a função fetch_sales_data_using_sqlite_query e adicioná-la ao conjunto de ferramentas
fetch_data_function = FunctionTool(fetch_sales_data_using_sqlite_query)
toolset.add(fetch_data_function)

# Inicializar ferramenta Code Interpreter e adicioná-la ao conjunto de ferramentas.
code_interpreter = code_interpreter = CodeInterpreterTool()
toolset.add(code_interpreter)

agent = project_client.agents.create_agent(
    model="gpt-4o-mini", name="my-agent", instructions="You are helpful agent", 
    toolset=toolset
)

Quais são as considerações especiais para usar o Padrão de Design de Uso de Ferramentas para construir agentes de IA confiáveis?

Uma preocupação comum com SQL gerado dinamicamente por LLMs é a segurança, particularmente o risco de injeção de SQL ou ações maliciosas, como apagar ou mexer no banco de dados. Embora essas preocupações sejam válidas, podem ser mitigadas efetivamente configurando corretamente as permissões de acesso ao banco de dados. Para a maioria dos bancos de dados, isso envolve configurá-lo como somente leitura. Para serviços de banco de dados como PostgreSQL ou Azure SQL, o aplicativo deve ser atribuído a um papel somente leitura (SELECT). Executar o aplicativo em um ambiente seguro aprimora ainda mais a proteção. Em cenários empresariais, os dados geralmente são extraídos e transformados de sistemas operacionais para um banco de dados ou data warehouse somente leitura com um esquema amigável ao usuário. Essa abordagem garante que os dados estejam seguros, otimizados para desempenho e acessibilidade, e que o aplicativo tenha acesso restrito e somente leitura.

Sample Codes

Got More Questions about the Tool Use Design Patterns?

Join the Azure AI Foundry Discord to meet with other learners, attend office hours and get your AI Agents questions answered.

Additional Resources

Previous Lesson

Understanding Agentic Design Patterns

Next Lesson

Agentic RAG

Aviso Legal: Este documento foi traduzido utilizando o serviço de tradução por IA Co-op Translator. Embora nos empenhemos para garantir a precisão, esteja ciente de que traduções automatizadas podem conter erros ou imprecisões. O documento original em seu idioma nativo deve ser considerado a fonte autoritativa. Para informações críticas, recomenda-se tradução profissional realizada por humanos. Não nos responsabilizamos por quaisquer mal-entendidos ou interpretações incorretas decorrentes do uso desta tradução.

This site is open source. Improve this page.