Function Calling

Integre ferramentas e funções externas aos modelos Urso com tool calling compatível com MCP.

Visão Geral

Function calling permite que os modelos Urso chamem funções externas durante a geração de respostas. O modelo decide quando e qual função chamar com base no contexto da conversa, retornando os argumentos estruturados para que sua aplicação execute a função e envie o resultado de volta.

A Polar também oferece ferramentas brasileiras nativas integradas (CEP, CNPJ, legislação, busca web).

Endpoint

POST https://api.polar-ai.com/v1/chat/completions

Use o endpoint de Chat Completions com o parâmetro tools.

Definindo Ferramentas

Cada ferramenta é definida com um nome, descrição e esquema de parâmetros JSON Schema:

{
  "type": "function",
  "function": {
    "name": "consultar_cep",
    "description": "Consulta informações de endereço a partir de um CEP brasileiro",
    "parameters": {
      "type": "object",
      "properties": {
        "cep": {
          "type": "string",
          "description": "CEP no formato 00000-000 ou 00000000"
        }
      },
      "required": ["cep"]
    }
  }
}

Parâmetro tool_choice

Controle quando o modelo deve usar ferramentas:

Valor	Descrição
`"auto"`	O modelo decide se deve chamar ferramentas (padrão)
`"required"`	O modelo deve chamar pelo menos uma ferramenta
`"none"`	O modelo não deve chamar ferramentas
`{"type": "function", "function": {"name": "..."}}`	Força uma ferramenta específica

Fluxo Completo

Python

import json
from openai import OpenAI

client = OpenAI(
    base_url="https://api.polar-ai.com/v1",
    api_key="pk-your-key-here"
)

# 1. Definir ferramentas
tools = [
    {
        "type": "function",
        "function": {
            "name": "consultar_cep",
            "description": "Consulta informações de endereço a partir de um CEP brasileiro",
            "parameters": {
                "type": "object",
                "properties": {
                    "cep": {
                        "type": "string",
                        "description": "CEP no formato 00000-000"
                    }
                },
                "required": ["cep"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "consultar_cnpj",
            "description": "Consulta dados de uma empresa a partir do CNPJ",
            "parameters": {
                "type": "object",
                "properties": {
                    "cnpj": {
                        "type": "string",
                        "description": "CNPJ no formato 00.000.000/0000-00"
                    }
                },
                "required": ["cnpj"]
            }
        }
    }
]

# 2. Enviar mensagem com ferramentas
messages = [
    {"role": "user", "content": "Qual o endereço do CEP 01001-000?"}
]

response = client.chat.completions.create(
    model="urso-base",
    messages=messages,
    tools=tools,
    tool_choice="auto"
)

message = response.choices[0].message

# 3. Verificar se o modelo quer chamar uma ferramenta
if message.tool_calls:
    # Adicionar mensagem do assistente ao histórico
    messages.append(message)

    for tool_call in message.tool_calls:
        function_name = tool_call.function.name
        arguments = json.loads(tool_call.function.arguments)

        # 4. Executar a função
        if function_name == "consultar_cep":
            result = consultar_cep(arguments["cep"])
        elif function_name == "consultar_cnpj":
            result = consultar_cnpj(arguments["cnpj"])

        # 5. Enviar resultado da ferramenta
        messages.append({
            "role": "tool",
            "tool_call_id": tool_call.id,
            "content": json.dumps(result)
        })

    # 6. Obter resposta final do modelo
    final_response = client.chat.completions.create(
        model="urso-base",
        messages=messages,
        tools=tools
    )

    print(final_response.choices[0].message.content)

TypeScript

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://api.polar-ai.com/v1",
  apiKey: "pk-your-key-here",
});

const tools: OpenAI.Chat.ChatCompletionTool[] = [
  {
    type: "function",
    function: {
      name: "consultar_cep",
      description: "Consulta informações de endereço a partir de um CEP brasileiro",
      parameters: {
        type: "object",
        properties: {
          cep: {
            type: "string",
            description: "CEP no formato 00000-000",
          },
        },
        required: ["cep"],
      },
    },
  },
];

const messages: OpenAI.Chat.ChatCompletionMessageParam[] = [
  { role: "user", content: "Qual o endereço do CEP 01001-000?" },
];

const response = await client.chat.completions.create({
  model: "urso-base",
  messages,
  tools,
  tool_choice: "auto",
});

const message = response.choices[0].message;

if (message.tool_calls) {
  messages.push(message);

  for (const toolCall of message.tool_calls) {
    const args = JSON.parse(toolCall.function.arguments);
    const result = await consultarCep(args.cep);

    messages.push({
      role: "tool",
      tool_call_id: toolCall.id,
      content: JSON.stringify(result),
    });
  }

  const finalResponse = await client.chat.completions.create({
    model: "urso-base",
    messages,
    tools,
  });

  console.log(finalResponse.choices[0].message.content);
}

curl

curl -X POST https://api.polar-ai.com/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer pk-your-key-here" \
  -d '{
    "model": "urso-base",
    "messages": [
      {"role": "user", "content": "Qual o endereço do CEP 01001-000?"}
    ],
    "tools": [
      {
        "type": "function",
        "function": {
          "name": "consultar_cep",
          "description": "Consulta informações de endereço a partir de um CEP brasileiro",
          "parameters": {
            "type": "object",
            "properties": {
              "cep": {
                "type": "string",
                "description": "CEP no formato 00000-000"
              }
            },
            "required": ["cep"]
          }
        }
      }
    ],
    "tool_choice": "auto"
  }'

Resposta com Tool Call

Quando o modelo decide chamar uma ferramenta:

{
  "id": "chatcmpl-abc123",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": null,
        "tool_calls": [
          {
            "id": "call_abc123",
            "type": "function",
            "function": {
              "name": "consultar_cep",
              "arguments": "{\"cep\": \"01001-000\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ]
}

Ferramentas Brasileiras Nativas

A Polar oferece ferramentas nativas que podem ser habilitadas automaticamente:

Ferramenta	Descrição
`polar_cep_lookup`	Consulta de endereço por CEP via ViaCEP
`polar_cnpj_query`	Consulta de dados empresariais por CNPJ
`polar_legislation_search`	Busca na legislação brasileira federal e estadual
`polar_web_search`	Busca na web em português brasileiro

Usando Ferramentas Nativas

response = client.chat.completions.create(
    model="urso-pro",
    messages=[
        {"role": "user", "content": "Busque a empresa com CNPJ 00.000.000/0001-91 e me diga o endereço dela."}
    ],
    tools=[
        {"type": "function", "function": {"name": "polar_cnpj_query"}},
        {"type": "function", "function": {"name": "polar_cep_lookup"}}
    ],
    tool_choice="auto"
)

Multi-turno com Ferramentas

O modelo pode chamar múltiplas ferramentas em sequência para resolver tarefas complexas:

messages = [
    {
        "role": "system",
        "content": "Você é um assistente jurídico. Use as ferramentas disponíveis para fundamentar suas respostas."
    },
    {
        "role": "user",
        "content": "Preciso saber se existe alguma lei federal sobre proteção de dados que se aplique à empresa no CNPJ 12.345.678/0001-90."
    }
]

# O modelo pode chamar polar_cnpj_query para dados da empresa
# e depois polar_legislation_search para buscar legislação relevante

Dicas de Uso

Forneça descrições claras e detalhadas para cada ferramenta
Use tool_choice="required" quando a ferramenta sempre deve ser usada
Valide os argumentos retornados pelo modelo antes de executar a função
Trate erros de ferramentas e envie mensagens de erro informativas ao modelo

Próximos Passos

Structured Output — combine com saída JSON estruturada
Streaming — receba tool calls em tempo real
Chat Completions — referência completa da API

On this page