Como Usar Function Calling com a API DeepSeek V4 Pro

DeepSeek tirou o V4 Pro da prévia em 12 de agosto de 2026, e a cobertura de lançamento destaca fluxos de trabalho de agente: codificação, uso de ferramentas e tarefas de longo prazo que encadeiam dezenas de etapas sem perder o contexto. Nesse cenário, a chamada de função (function calling) é o recurso central da API. Este guia mostra como definir ferramentas, executar o loop completo de um agente com o SDK Python openai e validar o fluxo no Apidog.

Experimente o Apidog hoje

Se você ainda não tem uma chave de API DeepSeek, configure uma com nosso guia sobre como usar a API DeepSeek V4 e retorne a este tutorial.

TL;DR

• deepseek-v4-pro (compilação GA DeepSeek-V4-Pro-0813) suporta chamadas de função no estilo OpenAI: envie um array tools, receba tool_calls e retorne resultados como mensagens tool. O SDK openai padrão funciona com https://api.deepseek.com.
• O loop completo do agente tem cerca de 30 linhas de Python: chame o modelo, execute ferramentas, adicione os resultados ao histórico e repita até receber uma resposta final.
• Chamadas paralelas e saídas estruturadas são suportadas. O modo de raciocínio adiciona reasoning_content.
• O cache de prefixo automático precifica tokens de entrada com acerto de cache em US$ 0,003625 por milhão de tokens, 120x menos que uma falha de cache.
• A qualidade da chamada de ferramenta depende das descrições e dos esquemas. Teste suas ferramentas reais com o modelo ao vivo.

Por que a chamada de ferramenta é o principal caso de uso do V4 Pro

A DeepSeek construiu o V4 Pro para agentes, e as especificações refletem requisitos comuns de runtimes de agentes:

Especificação	DeepSeek V4 Pro
Arquitetura	MoE esparsa: 1,6T parâmetros totais, 49B ativos por token
Janela de contexto	1M tokens
Saída máxima	384K tokens
Preço de entrada	US$ 0,435/M tokens (falha de cache), US$ 0,003625/M (acerto de cache)
Preço de saída	US$ 0,87/M tokens
Chamada de função	Array tools compatível com OpenAI e respostas tool_calls
Outras interfaces	Formato Anthropic Messages, API DeepSeek Responses

A janela de 1M de tokens permite carregar o histórico e os resultados de ferramentas em tarefas longas. O cache de prefixo reduz o custo de reenviar esse histórico a cada rodada. O modelo também está listado no OpenRouter como deepseek-v4-pro-0813 para comparações entre provedores.

Há uma ressalva importante: na discussão de lançamento no Hacker News, desenvolvedores relataram que o desempenho de chamadas de ferramenta varia com o ambiente de teste, o scaffolding do prompt e o estilo do esquema. Benchmarks não substituem testes com seus endpoints, parâmetros e regras de negócio.

Como funciona a chamada de função da DeepSeek

O modelo não executa funções diretamente. Ele retorna uma solicitação estruturada, por exemplo: “chame get_order com {"order_id": "ORD-10442"}”.

Seu aplicativo executa a função, devolve o resultado ao modelo e continua o fluxo.

O ciclo é:

1. Envie messages e o array tools, com cada ferramenta descrita em JSON Schema.
2. O modelo retorna tool_calls e finish_reason: "tool_calls" quando precisa de uma ferramenta.
3. Analise os argumentos e execute a função no seu backend.
4. Adicione o resultado como uma mensagem com role: "tool", vinculada ao ID da chamada.
5. Repita até o modelo retornar uma resposta final sem tool_calls.

Se você já usou chamada de função da OpenAI, o formato é o mesmo. Em muitos casos, basta alterar a URL base e o nome do modelo. Os documentos oficiais da DeepSeek também descrevem um endpoint de Mensagens compatível com Anthropic e uma API de Respostas, mas este artigo usa a interface compatível com OpenAI.

Passo 1: configure o cliente

Instale o SDK e defina sua chave:

pip install openai
export DEEPSEEK_API_KEY="sk-..."

Configure o cliente apontando para a API da DeepSeek:

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["DEEPSEEK_API_KEY"],
    base_url="https://api.deepseek.com",
)

Os exemplos usam model="deepseek-v4-pro", que se refere à compilação GA DeepSeek-V4-Pro-0813.

Passo 2: defina um esquema de ferramenta

Vamos criar um agente de suporte para uma loja online. A primeira ferramenta consulta pedidos.

Uma definição de ferramenta contém:

• Um nome estável para a função.
• Uma descrição clara de quando ela deve ser usada.
• Um JSON Schema para validar os parâmetros.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order",
            "description": (
                "Busca um pedido de cliente pelo ID. Retorna status, "
                "transportadora, código de rastreio e previsão de entrega. "
                "Use esta ferramenta quando o usuário perguntar onde está "
                "um pedido ou qual é seu status."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "ID do pedido no formato 'ORD-10442'.",
                    }
                },
                "required": ["order_id"],
            },
        },
    }
]

A descrição influencia diretamente a decisão do modelo. Se ela for vaga, o modelo pode ignorar a ferramenta ou selecionar uma função incorreta.

Agora implemente a função local. Neste exemplo, ela usa dados simulados; em produção, substitua-a pela chamada ao seu serviço de pedidos.

def get_order(order_id: str) -> dict:
    """Substitua pelo seu serviço real de pedidos."""
    fake_db = {
        "ORD-10442": {
            "status": "shipped",
            "carrier": "DHL",
            "tracking_number": "4281337005",
            "estimated_delivery": "2026-08-15",
        },
        "ORD-10587": {
            "status": "processing",
            "estimated_ship_date": "2026-08-14",
        },
    }

    return fake_db.get(
        order_id,
        {"error": f"ID de pedido desconhecido: {order_id}"},
    )

Passo 3: faça sua primeira chamada de ferramenta

Envie uma pergunta que exige consulta ao sistema de pedidos:

messages = [
    {
        "role": "system",
        "content": "Você é um agente de suporte de uma loja online.",
    },
    {
        "role": "user",
        "content": "Onde está meu pedido ORD-10442?",
    },
]

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools,
)

message = response.choices[0].message

print(message.tool_calls[0].function.name)
# get_order

print(message.tool_calls[0].function.arguments)
# {"order_id": "ORD-10442"}

Em vez de inventar uma resposta, o modelo solicita que seu código execute get_order.

Um payload de resposta típico é:

{
  "id": "chatcmpl-8f3a1c",
  "object": "chat.completion",
  "model": "deepseek-v4-pro",
  "choices": [
    {
      "index": 0,
      "message": {
        "role": "assistant",
        "content": "",
        "tool_calls": [
          {
            "id": "call_0_f1c29a44",
            "type": "function",
            "function": {
              "name": "get_order",
              "arguments": "{\"order_id\": \"ORD-10442\"}"
            }
          }
        ]
      },
      "finish_reason": "tool_calls"
    }
  ],
  "usage": {
    "prompt_tokens": 312,
    "completion_tokens": 24,
    "total_tokens": 336,
    "prompt_cache_hit_tokens": 0,
    "prompt_cache_miss_tokens": 312
  }
}

Três detalhes são essenciais:

• finish_reason igual a "tool_calls" indica que você deve executar ferramentas.
• Cada chamada tem um id exclusivo, que precisa ser retornado em tool_call_id.
• arguments é uma string JSON. Faça o parsing e valide o conteúdo antes de executar qualquer operação.

Passo 4: execute a função e retorne o resultado

Adicione ao histórico a mensagem do assistente que contém tool_calls. Em seguida, adicione uma mensagem tool com o resultado da execução.

import json

tool_call = message.tool_calls[0]
args = json.loads(tool_call.function.arguments)

result = get_order(**args)

messages.append(message)

messages.append({
    "role": "tool",
    "tool_call_id": tool_call.id,
    "content": json.dumps(result),
})

final = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools,
)

print(final.choices[0].message.content)
# Seu pedido ORD-10442 foi enviado pela DHL e deve chegar
# em 15 de agosto de 2026. Código de rastreio: 4281337005.

O vínculo pelo tool_call_id é obrigatório: para cada item em tool_calls, envie uma mensagem tool correspondente antes da próxima chamada ao modelo.

Passo 5: implemente o ciclo completo do agente

Agentes reais encadeiam chamadas: consultar um pedido, buscar uma política de reembolso, verificar estoque e redigir uma resposta. O padrão é sempre o mesmo: chamar o modelo, executar as ferramentas solicitadas e repetir até obter uma resposta normal.

import json

TOOLS_BY_NAME = {
    "get_order": get_order,
}

def run_agent(client, messages, tools, max_rounds=10):
    """Executa o agente até obter uma resposta final ou atingir o limite."""
    for _ in range(max_rounds):
        response = client.chat.completions.create(
            model="deepseek-v4-pro",
            messages=messages,
            tools=tools,
        )

        message = response.choices[0].message
        messages.append(message)

        if not message.tool_calls:
            return message.content

        for tool_call in message.tool_calls:
            try:
                fn = TOOLS_BY_NAME.get(tool_call.function.name)

                if fn is None:
                    raise ValueError(
                        f"Ferramenta desconhecida: {tool_call.function.name}"
                    )

                args = json.loads(tool_call.function.arguments)
                result = fn(**args)

            except Exception as exc:
                result = {"error": str(exc)}

            messages.append({
                "role": "tool",
                "tool_call_id": tool_call.id,
                "content": json.dumps(result),
            })

    raise RuntimeError(
        f"O agente não terminou após {max_rounds} rodadas"
    )

O limite max_rounds é uma proteção operacional. Ele evita que um modelo preso em chamadas repetidas gere custos e execuções indefinidas.

Chamadas de ferramenta paralelas

Para uma pergunta como “compare o status de ORD-10442 e ORD-10587”, o V4 Pro pode retornar várias chamadas em uma única resposta:

"tool_calls": [
  {
    "id": "call_0_a7d1",
    "type": "function",
    "function": {
      "name": "get_order",
      "arguments": "{\"order_id\": \"ORD-10442\"}"
    }
  },
  {
    "id": "call_1_b3e9",
    "type": "function",
    "function": {
      "name": "get_order",
      "arguments": "{\"order_id\": \"ORD-10587\"}"
    }
  }
]

O loop anterior já suporta esse caso: ele cria uma mensagem tool para cada tool_call. Se suas ferramentas forem independentes, você pode executar o lote concorrentemente com asyncio, um pool de threads ou sua fila de jobs.

Isso difere da chamada de ferramenta programática do GPT-5.6, em que o modelo escreve código de orquestração em um sandbox. No modelo da DeepSeek, a execução continua sob controle do seu runtime.

Modo de raciocínio (thinking mode) e ferramentas

O V4 Pro oferece três modos de raciocínio. Você pode usar mais esforço de raciocínio em rodadas de planejamento e ignorá-lo em consultas rotineiras. Consulte os documentos oficiais para os nomes e padrões dos modos.

Com o raciocínio ativado, a API retorna reasoning_content junto com tool_calls:

response = client.chat.completions.create(
    model="deepseek-v4-pro",
    messages=messages,
    tools=tools,
    extra_body={"thinking": {"type": "enabled"}},
)

message = response.choices[0].message

print(message.reasoning_content)
print(message.tool_calls)

O rastreamento pode ajudar a identificar por que o modelo escolheu uma ferramenta ou interpretou um parâmetro de forma incorreta.

Antes de adicionar a mensagem do assistente ao histórico, remova reasoning_content quando não precisar preservá-lo. Reserve o raciocínio para etapas de planejamento, pois ele é cobrado como saída a US$ 0,87/M tokens.

Tratamento de erros: quando o modelo erra uma chamada

Chamadas malformadas são raras, mas precisam ser tratadas. Não interrompa o agente por causa de um JSON inválido ou de parâmetros fora das regras de negócio. Retorne o erro como resultado da ferramenta para que o modelo possa corrigir a chamada na próxima rodada.

import json
from jsonschema import ValidationError, validate

schema = tools[0]["function"]["parameters"]

try:
    args = json.loads(tool_call.function.arguments)
    validate(instance=args, schema=schema)

    result = get_order(**args)

except (json.JSONDecodeError, ValidationError) as exc:
    result = {
        "error": f"Argumentos inválidos: {exc}",
        "hint": (
            "Chame get_order novamente usando um order_id no formato "
            "'ORD-10442'."
        ),
    }

O campo hint torna a correção explícita e costuma ser suficiente para o modelo tentar novamente com argumentos válidos.

Trate erros de ferramenta também como eventos de segurança. Um modelo induzido a chamar delete_order com argumentos maliciosos é tão perigoso quanto as credenciais disponíveis para essa ferramenta. Use chaves de API com o menor privilégio para agentes de IA e limite o escopo de cada integração.

Teste e depure chamadas de ferramenta com Apidog antes de lançar

Cada ferramenta é um invólucro em torno de uma API, e o modelo passa a ser um consumidor dessa API. Se o endpoint for ambíguo, inconsistente ou retornar erros difíceis de interpretar, o agente herdará esse problema.

Use o Apidog para validar o fluxo antes de conectar o agente à produção:

1. Projete a API de suporte primeiro. Defina GET /orders/{order_id} no designer visual do Apidog. Mantenha o JSON Schema da ferramenta alinhado à especificação da API para evitar divergências.
2. Simule antes de o backend existir. O mock inteligente do Apidog pode gerar respostas realistas a partir do esquema, permitindo testar get_order enquanto o serviço real ainda está em desenvolvimento.
3. Inspecione payloads brutos. Envie o mesmo corpo com messages e tools para https://api.deepseek.com pelo Apidog. Inspecione o JSON de tool_calls para identificar propriedades aninhadas incorretamente e argumentos serializados duas vezes.
4. Transforme conversas em cenários de teste. Valide finish_reason, nomes de ferramentas e formatos de argumentos. Execute a suíte a cada alteração de esquema. Como o comportamento depende do formato das ferramentas, uma regressão baseada nos seus cenários reais é mais útil que benchmarks genéricos.

Veja também como conectar um agente de IA a uma estrutura de teste Apidog para um padrão mais aprofundado.

Baixe o Apidog gratuitamente para acompanhar. O servidor de mock e os cenários de teste estão incluídos na camada gratuita.

Quanto custam os ciclos de agente — e por que o cache decide isso

Um agente relê o histórico inteiro a cada rodada. Na décima rodada, o prompt de sistema, as definições de ferramentas e os resultados anteriores voltam a fazer parte da entrada.

O cache de prefixo automático do V4 Pro reduz esse custo porque a entrada de cada rodada tende a ser igual à rodada anterior, acrescida de novas mensagens. Assim, a maior parte do prefixo pode ser cobrada a US$ 0,003625/M tokens, em vez de US$ 0,435/M tokens.

Reler uma conversa de 100K tokens custa aproximadamente:

• Sem cache: US$ 0,0435
• Com cache: US$ 0,0004

Monitore prompt_cache_hit_tokens e prompt_cache_miss_tokens no bloco usage para observar a taxa de acerto real.

Para manter o cache eficiente:

• Não altere mensagens já enviadas.
• Mantenha o array tools estável entre as rodadas.
• Evite reordenar ferramentas ou mudar descrições durante uma conversa.
• Serialize os schemas de forma consistente.

Nosso guia sobre o que é cache de prompt cobre a mecânica em mais detalhes.

Embora deepseek-v4-flash a US$ 0,14/US$ 0,28 possa parecer atraente para roteamento de ferramenta de uso único, ele regride em ciclos com mais de 10 chamadas encadeadas. Para agentes com múltiplas etapas, o Pro é a opção mais segura.

FAQ

As definições de ferramentas custam tokens?

Sim. O array tools faz parte da entrada de cada solicitação. Mantenha-o estável para que ele entre no prefixo em cache após a primeira rodada e seja cobrado pela taxa de acerto de cache.

Posso combinar chamada de função com saídas estruturadas?

Sim. Um padrão comum é:

1. Ferramentas buscam dados intermediários.
2. O modelo processa esses dados.
3. Um esquema de saída estruturado formata a resposta final.

Assim, seu código downstream recebe JSON previsível sem precisar analisar texto livre.

Conclusão

A chamada de função no DeepSeek V4 Pro é simples de implementar: defina schemas compatíveis com OpenAI, processe tool_calls e devolva resultados em mensagens tool vinculadas pelo ID.

O loop do Passo 5 é a base da arquitetura. O ponto crítico não é apenas o código: são os schemas, a validação, os limites de execução, as permissões das credenciais e os testes de regressão.

Projete as APIs de suporte de forma deliberada, simule endpoints cedo e mantenha cenários de teste para as chamadas reais do seu agente no Apidog. Isso reduz o risco de uma alteração de esquema quebrar silenciosamente o fluxo em produção.