Tutorial de chamada de ferramentas no Ollama: como usar function calling

Modelos de linguagem não sabem como está o clima hoje, o que há no seu banco de dados nem são bons em cálculos precisos. A chamada de ferramentas (tool calling, também chamada de function calling) permite que o modelo peça ao seu programa para executar uma função e, em seguida, responda com base no resultado.

Esse recurso só funciona com modelos compatíveis com ferramentas. Na página do modelo em ollama.com, procure a indicação tools, como em qwen3, llama3.1, gpt-oss e mistral.

Como funciona

1. Você: pergunta + descrição das ferramentas disponíveis ──────────▶ Modelo
2. Modelo: "Chame get_weather(city=\"台北\")"◀──
3. Seu programa executa get_weather("台北") → "24°C，多雲"
4. Você: envia o resultado de volta ─────────────────────▶ Modelo
5. Modelo: "台北現在 24 度、多雲，建議帶件薄外套。"

O modelo não executa nenhum código por conta própria; ele apenas decide qual ferramenta chamar e quais parâmetros usar. Quem realmente executa é o seu programa, então você controla totalmente o que ele pode fazer.

Exemplo em Python

O pacote Python do Ollama permite passar funções Python diretamente como ferramentas. Ele gera automaticamente a descrição da ferramenta a partir das anotações de tipo e da docstring da função:

from ollama import chat


def get_weather(city: str) -> str:
    """
    Consulta o clima atual de uma cidade.

    Args:
        city: Nome da cidade, por exemplo, "台北"

    Returns:
        Descrição do clima
    """
    fake_data = {"台北": "24°C, nublado", "高雄": "29°C, ensolarado"}
    return fake_data.get(city, "Dados indisponíveis")


tools = {"get_weather": get_weather}
messages = [{"role": "user", "content": "Como está o clima agora em 台北 e 高雄?"}]

response = chat(model="qwen3:8b", messages=messages, tools=[get_weather])
messages.append(response.message)

# O modelo pode pedir várias chamadas de ferramenta de uma só vez
for call in response.message.tool_calls or []:
    fn = tools[call.function.name]
    result = fn(**call.function.arguments)
    print(f"Chamando {call.function.name}({call.function.arguments}) → {result}")
    messages.append({"role": "tool", "tool_name": call.function.name, "content": str(result)})

final = chat(model="qwen3:8b", messages=messages)
print(final.message.content)

Pontos principais:

1. Adicione a resposta do modelo (incluindo tool_calls) de volta a messages.
2. Adicione o resultado de cada ferramenta usando role: "tool".
3. Chame chat novamente para que o modelo responda com base nos resultados.

Deixe o modelo decidir quantas chamadas fazer

Algumas perguntas exigem chamadas sucessivas a várias ferramentas, por exemplo, "consulte primeiro a taxa de câmbio e depois calcule o valor". Use um loop até que o modelo pare de pedir chamadas de ferramenta:

from ollama import chat


def get_exchange_rate(currency: str) -> float:
    """Obtém a taxa de câmbio de 1 unidade de moeda estrangeira para o novo dólar taiwanês. currency, por exemplo, USD, JPY."""
    return {"USD": 32.1, "JPY": 0.21}.get(currency.upper(), 0.0)


def multiply(a: float, b: float) -> float:
    """Multiplica a por b."""
    return a * b


tools = {f.__name__: f for f in [get_exchange_rate, multiply]}
messages = [{"role": "user", "content": "Quanto são aproximadamente 350 dólares americanos em novos dólares taiwaneses?"}]

while True:
    response = chat(model="qwen3:8b", messages=messages, tools=list(tools.values()))
    messages.append(response.message)
    if not response.message.tool_calls:
        break
    for call in response.message.tool_calls:
        result = tools[call.function.name](**call.function.arguments)
        messages.append({"role": "tool", "tool_name": call.function.name, "content": str(result)})

print(response.message.content)

Na prática, defina um limite para o número de chamadas para evitar que o modelo entre em um loop infinito.

Defina ferramentas com a REST API

Sem o pacote Python, descreva as ferramentas com JSON Schema:

curl http://localhost:11434/api/chat -d '{
  "model": "qwen3:8b",
  "messages": [{ "role": "user", "content": "Como está o clima em 台北?" }],
  "stream": false,
  "tools": [{
    "type": "function",
    "function": {
      "name": "get_weather",
      "description": "Consulta o clima atual de uma cidade",
      "parameters": {
        "type": "object",
        "properties": {
          "city": { "type": "string", "description": "Nome da cidade" }
        },
        "required": ["city"]
      }
    }
  }]
}'

Em message.tool_calls, a resposta contém:

"tool_calls": [
  { "function": { "name": "get_weather", "arguments": { "city": "São Paulo" } } }
]

Depois de executar a ferramenta, adicione o resultado a messages usando {"role": "tool", "tool_name": "get_weather", "content": "24°C, nublado"} e envie novamente.

Escreva boas descrições para as ferramentas

O modelo decide quando usar uma ferramenta e como preencher os parâmetros com base exclusivamente no nome e na descrição dela:

• Escolha um nome que deixe clara a finalidade da função: search_orders é melhor que query1.
• Explique na descrição em que situações usar a ferramenta, o formato dos parâmetros e exemplos.
• Mantenha poucos parâmetros e use tipos explícitos. Prefira uma enumeração (enum) quando possível.
• Evite oferecer ferramentas demais. Modelos pequenos podem escolher errado quando têm de lidar com mais de dez ferramentas.

Cuidados de segurança

• O modelo aciona ferramentas com base na entrada do usuário. Se o usuário puder controlar a entrada, poderá chamar suas ferramentas indiretamente.
• Não ofereça ferramentas que executem código arbitrário ou SQL arbitrário, nem que apaguem dados.
• Para ações com efeitos colaterais (pagamentos, envio de e-mails, exclusão), peça a confirmação do usuário antes de executar.
• Valide os parâmetros fornecidos pelo modelo; não confie neles diretamente.

Atualizado 12 de outubro de 2026