ai-agents-for-beginners

Como Projetar Bons Agentes de IA

(Clique na imagem acima para assistir ao vídeo desta aula)

Padrão de Design para Uso de Ferramentas

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

Introdução

Nesta aula, buscamos responder às seguintes perguntas:

Objetivos de Aprendizagem

Após concluir esta aula, você será capaz de:

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

O Padrão de Design para Uso de Ferramentas foca em dar aos LLMs a habilidade 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 API para um serviço de terceiros como consulta de preço de ações ou previsão do tempo. No contexto de agentes de IA, as 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 em que pode ser aplicado?

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

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

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

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

Chamada de Função/Ferramenta

A chamada de função é a forma principal pela qual habilitamos Modelos de Linguagem Grande (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 executar tarefas. Para que o código de uma função seja invocado, um LLM deve comparar a solicitação 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 essa informação para responder à solicitação do usuário.

Para os desenvolvedores implementarem a chamada de função para agentes, será necessário:

  1. Um modelo LLM que suporte chamada 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 o horário atual em uma cidade para ilustrar:

  1. Inicializar um LLM que suporta chamada de função:

    Nem todos os modelos suportam chamada de função, então é importante verificar se o LLM que você está usando suporta. Azure OpenAI suporta chamada de função. Podemos começar iniciando o cliente OpenAI contra a API de Respostas do Azure OpenAI (o endpoint estável /openai/v1/ — não é necessário api_version).

     # Inicialize o cliente OpenAI para Azure OpenAI (API de Respostas, endpoint v1)
 client = OpenAI(
     base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
     api_key=os.environ["AZURE_OPENAI_API_KEY"],
 )
 deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT"]

  2. Criar um Esquema de Função:

    Em seguida, vamos definir um esquema JSON que contém o nome da função, a descrição do que a função faz, e os nomes e descrições dos parâmetros da função. Depois vamos passar esse esquema para o cliente criado anteriormente, junto com a solicitação do usuário para encontrar o horário 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 para ela.

     # Descrição da função para o modelo ler (formato ferramenta plana da API de Respostas)
 tools = [
     {
         "type": "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 de API: Peça ao modelo para usar a função
 response = client.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     tool_choice="auto",
     store=False,
 )

 # A API de Respostas retorna chamadas de ferramentas como itens function_call em response.output.
 # Adicione-os à conversa para que o modelo tenha o contexto completo na próxima vez.
 messages += response.output

 print("Model's response:")
 print(response.output)
  

     Model's response:
 [ResponseFunctionToolCall(arguments='{"location":"San Francisco"}', call_id='call_pOsKdUlqvdyttYB67MOj434b', name='get_current_time', type='function_call')]

  3. O código da função necessário para executar 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 o horário 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
 tool_calls = [item for item in response.output if item.type == "function_call"]
 if tool_calls:
     for tool_call in tool_calls:
         if tool_call.name == "get_current_time":

             function_args = json.loads(tool_call.arguments)

             time_response = get_current_time(
                 location=function_args.get("location")
             )

             # Retornar o resultado da ferramenta como um item function_call_output
             messages.append({
                 "type": "function_call_output",
                 "call_id": tool_call.call_id,
                 "output": 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.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     store=False,
 )

 return final_response.output_text

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

A chamada de funções está no coração da maioria, senão de todos, os projetos de uso de ferramentas para agentes, contudo, implementá-la do zero pode ser desafiador às vezes. Como aprendemos na Aula 2, frameworks agenticos nos fornecem blocos de construção pré-construídos para implementar o uso de ferramentas.

Exemplos de Uso de Ferramentas com Frameworks Agenticos

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

Microsoft Agent Framework

Microsoft Agent Framework é um framework de IA open-source para construir agentes de IA. Ele simplifica o processo de uso de chamadas de função permitindo que você defina ferramentas como funções Python com o decorador @tool. O framework gerencia a comunicação entre o modelo e seu código. Também fornece acesso a ferramentas pré-construídas como Busca de Arquivos e Interpretador de Código através do FoundryChatClient.

O diagrama a seguir ilustra o processo de chamada de função com o Microsoft Agent Framework:

chamada de função

No Microsoft Agent Framework, ferramentas são definidas como funções decoradas. Podemos converter a função get_current_time que vimos antes em uma ferramenta usando o decorador @tool. O framework automaticamente serializará a função e seus parâmetros, criando o esquema para enviar ao LLM.

import os
from agent_framework import tool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

@tool(approval_mode="never_require")
def get_current_time(location: str) -> str:
    """Get the current time for a given location"""
    ...

# Crie o cliente
provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)

# Crie um agente e execute com a ferramenta
agent = provider.as_agent(name="TimeAgent", instructions="Use available tools to answer questions.", tools=get_current_time)
response = await agent.run("What time is it?")

Microsoft Foundry Agent Service

Microsoft Foundry Agent Service é um framework agentico mais recente, projetado para capacitar desenvolvedores a construir, implantar 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 corporativo.

Quando comparado ao desenvolvimento direto com a API do LLM, o Microsoft Foundry Agent Service oferece algumas vantagens, incluindo:

As ferramentas disponíveis no Microsoft Foundry 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 juntas como um conjunto de ferramentas. Ele também utiliza threads que mantêm o histórico das mensagens de uma determinada conversa.

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

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

Agentic Service em Ação

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 em Python. O LLM poderá analisar o conjunto de ferramentas e decidir se usa a função criada pelo usuário, fetch_sales_data_using_sqlite_query, ou o Interpretador de Código pré-construído, dependendo da solicitação 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 = CodeInterpreterTool()toolset.add(code_interpreter)

agent = project_client.agents.create_agent(
    model="gpt-5-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 para 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 adulterar o banco de dados. Embora essas preocupações sejam válidas, elas podem ser mitigadas efetivamente configurando apropriadamente as permissões de acesso ao banco de dados. Para a maioria dos bancos de dados, isso envolve configurar o banco como somente leitura. Para serviços de banco de dados como PostgreSQL ou Azure SQL, o aplicativo deve receber um papel somente leitura (SELECT).

Executar o aplicativo em um ambiente seguro aumenta ainda mais a proteção. Em cenários empresariais, dados são tipicamente extraídos e transformados de sistemas operacionais para um banco de dados somente leitura ou data warehouse com um esquema amigável. Essa abordagem assegura que os dados estejam seguros, otimizados para desempenho e acessibilidade, e que o app tenha acesso restrito, somente leitura.

Códigos de Exemplo

Tem Mais Perguntas sobre os Padrões de Design para Uso de Ferramentas?

Junte-se ao Microsoft Foundry Discord para conhecer outros aprendizes, participar de horas de plantão e tirar suas dúvidas sobre Agentes de IA.

Recursos Adicionais

Testando rapidamente este Agente (Opcional)

Após aprender a implantar agentes em Lição 16, você pode testar rapidamente o TravelToolAgent desta lição (ele ainda chama suas ferramentas e responde?) usando tests/lesson-04-smoke-tests.json. Veja tests/README.md para saber como executá-lo.

Lição Anterior

Entendendo Padrões de Design Agentes

Próxima Lição

Agentic RAG

Aviso Legal: Este documento foi traduzido usando o serviço de tradução por IA Co-op Translator. Embora nos esforcemos pela precisão, por favor, 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 autorizada. Para informações críticas, recomenda-se tradução profissional humana. 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.