DeepSeek Tool Calls: guia completo para usar funções na API

DeepSeek Tool Calls é o recurso da API DeepSeek que permite ao modelo solicitar o uso de funções externas, como consultar um pedido, buscar dados em um CRM, verificar estoque ou criar um ticket de suporte. O ponto mais importante é: o modelo não executa a função sozinho. Ele gera uma solicitação estruturada, e o seu backend valida os argumentos, executa a função real e devolve o resultado para o modelo produzir a resposta final. A própria documentação da DeepSeek destaca que a função precisa ser fornecida pelo usuário e que o modelo não executa funções específicas por conta própria.

Em outras palavras, Tool Calls conectam um LLM a sistemas reais. Sem isso, o modelo responde com base no contexto que recebeu. Com isso, ele pode pedir ao seu sistema para consultar dados atualizados, executar uma operação controlada ou chamar uma API externa. Este guia é para quem quer implementar chamadas de ferramentas na API DeepSeek, com exemplos práticos, segurança, tool_choice, strict mode, Thinking Mode e boas práticas para produção.

---

TL;DR

• DeepSeek Tool Calls permite que o modelo peça a execução de funções externas.
• O modelo não executa a função; quem executa é a aplicação, serviço ou backend.
• O fluxo básico é: usuário pergunta → modelo retorna tool_calls → backend valida → backend executa → aplicação envia role="tool" → modelo responde.
• O parâmetro tools lista as funções disponíveis para o modelo, e a documentação informa que atualmente apenas funções são suportadas como ferramentas, com limite de até 128 funções.
• tool_choice controla se o modelo pode, deve, não deve ou é forçado a chamar uma função específica.
• strict mode é uma funcionalidade Beta que ajuda o modelo a respeitar o JSON Schema da função, mas não substitui validação no backend.
• Tool Calls também funciona em Thinking Mode, mas quando há chamada de ferramenta o reasoning_content precisa ser preservado internamente em solicitações subsequentes, conforme a documentação oficial.

---

---

O que é DeepSeek Tool Calls?

DeepSeek Tool Calls é o mecanismo que permite ao modelo retornar uma chamada estruturada para uma função definida pela sua aplicação. Em vez de responder apenas com texto, o modelo pode indicar algo como: “para responder corretamente, preciso chamar a função get_order_status com o argumento order_id igual a BR12345”.

Essa função não existe dentro do modelo. Ela existe no seu sistema. A sua aplicação declara a função no parâmetro tools, descreve o que ela faz e informa quais argumentos aceita usando JSON Schema. Quando o modelo entende que precisa dessa ferramenta, ele retorna um objeto tool_calls com o nome da função e os argumentos em formato JSON.

A regra central é simples:

O modelo solicita; o backend valida e executa.

Esse detalhe é essencial para segurança, arquitetura e confiabilidade. O modelo pode gerar argumentos incorretos, incompletos ou fora das regras do seu negócio. Por isso, a documentação oficial alerta que os argumentos gerados pelo modelo devem ser validados no código antes de chamar a função real.

Um exemplo prático em português brasileiro:

Usuário: “Qual é o status do meu pedido 78910?”

O modelo pode retornar uma chamada para:

{
  "name": "get_order_status",
  "arguments": {
    "order_id": "78910"
  }
}

Depois disso, o backend consulta o banco de dados, valida se o usuário tem permissão para ver o pedido, obtém o status e envia o resultado de volta para a API DeepSeek como uma mensagem role="tool".

---

Como DeepSeek Tool Calls funciona na prática

O fluxo de Tool Calls é uma conversa em duas ou mais etapas. A primeira etapa é a solicitação do usuário. A segunda é a resposta do modelo dizendo se precisa ou não chamar uma ferramenta. A terceira é a execução real no backend. A quarta é o retorno do resultado para o modelo gerar a resposta final.

Etapa	Responsável	O que acontece
1	Usuário	Envia uma pergunta, pedido ou comando para a aplicação.
2	Aplicação	Envia messages e tools para a API DeepSeek.
3	Modelo	Decide responder diretamente ou retornar tool_calls.
4	Backend	Valida o nome da função e os argumentos recebidos.
5	Backend	Executa a função real, como consultar pedido, CRM ou estoque.
6	Aplicação	Adiciona uma mensagem role="tool" com o tool_call_id.
7	Aplicação	Chama novamente a API DeepSeek com o resultado da ferramenta.
8	Modelo	Gera a resposta final em linguagem natural para o usuário.

A documentação oficial mostra esse mesmo padrão: o modelo retorna uma chamada, o usuário ou aplicação chama a função e fornece o resultado, e então o modelo responde em linguagem natural. Também deixa claro que a função precisa ser implementada pelo usuário, não pelo modelo.

Esse fluxo torna Tool Calls útil para aplicações que precisam responder com dados vivos. Por exemplo, um chatbot de e-commerce pode consultar o status de entrega; um assistente interno pode buscar dados de um cliente no CRM; um agente de suporte pode abrir um ticket com prioridade correta.

---

DeepSeek Tool Calls vs Function Calling

“Function Calling” é o nome mais conhecido no ecossistema de LLMs para esse padrão de integração. “Tool Calls” é o nome usado na documentação da DeepSeek para representar chamadas de ferramentas, atualmente com suporte a funções como tipo de ferramenta. A documentação de Create Chat Completion define tools como uma lista de ferramentas que o modelo pode chamar e informa que atualmente apenas funções são suportadas.

Termo	Significado prático	Quando usar
DeepSeek Tool Calls	Nome usado na API DeepSeek para chamadas de ferramentas.	Quando estiver implementando com a DeepSeek API.
DeepSeek Function Calling	Termo comum usado por desenvolvedores para se referir ao mesmo padrão.	Quando estiver pesquisando tutoriais, exemplos e integrações.
Function	A função real definida pela sua aplicação.	Para consultar dados, executar ações ou integrar serviços.
Tool	A representação da função enviada ao modelo no parâmetro tools.	Para informar ao modelo quais capacidades externas estão disponíveis.

Na prática, você pode pensar em Tool Calls como a camada de comunicação entre o modelo e o seu backend. O modelo escolhe a ferramenta; seu sistema decide se a chamada é válida.

---

Tool Calls vs JSON Output vs RAG vs Agents

Tool Calls não substitui todos os outros recursos de uma aplicação com LLM. Ele resolve um problema específico: permitir que o modelo peça a execução de funções externas. JSON Output, RAG e agents são conceitos relacionados, mas diferentes.

Recurso	O que faz	Quando usar	Quando evitar
Tool Calls	Permite que o modelo solicite funções externas.	Consultar APIs, banco de dados, CRM, estoque, agenda ou tickets.	Quando a resposta pode ser gerada apenas com texto.
JSON Output	Força ou orienta a saída em formato JSON.	Extrair campos, classificar dados, gerar payloads estruturados.	Quando é necessário executar uma ação real em outro sistema.
RAG	Recupera documentos ou dados relevantes para inserir no contexto.	Responder com base em base de conhecimento, documentos ou políticas internas.	Quando é preciso alterar dados ou executar uma operação.
Agents	Coordenam múltiplas etapas, ferramentas e decisões.	Automatizar fluxos complexos com várias ações.	Quando uma única chamada simples resolve o problema.

Um exemplo: se o usuário pergunta “qual é a política de troca?”, RAG pode ser suficiente. Se ele pergunta “abra uma solicitação de troca para meu pedido”, Tool Calls é mais adequado, porque há uma ação real a ser executada.

---

Campos principais da API

Para usar DeepSeek Tool Calls corretamente, você precisa entender os campos principais envolvidos no fluxo.

tools

tools é a lista de ferramentas disponíveis para o modelo. Segundo a referência oficial, atualmente apenas funções são suportadas como ferramentas, e o limite documentado é de até 128 funções.

function.name

É o nome da função que o modelo poderá chamar. A documentação informa que o nome deve usar caracteres permitidos como letras, números, underscores ou hífens, com comprimento máximo de 64 caracteres.

Exemplo:

"name": "get_order_status"

function.description

É a descrição que ajuda o modelo a entender quando e como usar aquela função. Uma descrição ruim aumenta a chance de chamadas erradas.

Exemplo bom:

"description": "Consulta o status de um pedido pelo ID, apenas para pedidos do usuário autenticado."

parameters

Define os argumentos aceitos pela função usando JSON Schema. Se a função recebe order_id, customer_id ou priority, esses campos devem ser descritos aqui. A documentação oficial aponta que parameters descreve os argumentos aceitos pela função no formato JSON Schema.

JSON Schema

É o contrato estrutural dos argumentos. Use type, properties, required, enum e additionalProperties para restringir entradas. Em strict mode, a DeepSeek documenta suporte a tipos como object, string, number, integer, boolean, array, enum e anyOf.

tool_choice

Controla se o modelo pode ou deve chamar uma ferramenta. Os valores documentados incluem none, auto, required e a possibilidade de forçar uma função específica pelo nome.

tool_call_id

É o ID da chamada de ferramenta retornada pelo modelo. Quando você devolve o resultado da ferramenta, precisa usar o mesmo tool_call_id, permitindo que o modelo associe o resultado à chamada correta. A referência oficial descreve tool_call_id como o identificador da chamada à qual a mensagem de ferramenta está respondendo.

role="tool"

É o papel usado na mensagem que devolve o resultado da função para o modelo. A documentação define mensagens com papel tool, conteúdo textual e tool_call_id obrigatório.

strict

Quando strict é true, a API tenta garantir que a chamada de ferramenta siga o JSON Schema da função. A documentação descreve o strict mode como Beta e exige o uso de base_url="https://api.deepseek.com/beta" para habilitar recursos Beta.

---

Quais modelos DeepSeek suportam Tool Calls?

Conforme a documentação atual da DeepSeek, os modelos listados na API são deepseek-v4-flash e deepseek-v4-pro, com suporte a JSON Output e Tool Calls. A página de Models & Pricing também informa que ambos suportam modos thinking e non-thinking, contexto de 1M e saída máxima de 384K.

Modelo	Quando considerar
deepseek-v4-flash	Quando você precisa de menor latência, boa relação custo-benefício e fluxos operacionais frequentes.
deepseek-v4-pro	Quando você precisa de maior capacidade para tarefas complexas, raciocínio mais exigente ou agentes com múltiplas etapas.

A DeepSeek também publicou que, na transição para V4, a base_url permanece a mesma e o parâmetro model deve ser atualizado para deepseek-v4-pro ou deepseek-v4-flash. A mesma publicação informa que os aliases legacy deepseek-chat e deepseek-reasoner serão aposentados em 24 de julho de 2026, às 15:59 UTC.

Para produção, evite depender de aliases antigos. Use os nomes atuais dos modelos e revise a documentação oficial periodicamente, especialmente porque nomes, preços e disponibilidade podem mudar.

---

Exemplo prático com Python

A seguir está um exemplo completo em Python para consultar o status de um pedido. Ele usa o SDK da OpenAI com base_url da DeepSeek, como a própria documentação oficial demonstra para chamadas no formato OpenAI.

Cenário: o usuário pergunta pelo status de um pedido. O modelo decide chamar get_order_status. O backend valida os argumentos, executa a função real e devolve o resultado para o modelo.

import os
import json
from typing import Any, Dict

from openai import OpenAI

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

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_order_status",
            "description": (
                "Consulta o status de um pedido pelo ID. "
                "Use apenas quando o usuário pedir informações sobre um pedido."
            ),
            "parameters": {
                "type": "object",
                "properties": {
                    "order_id": {
                        "type": "string",
                        "description": "ID do pedido, por exemplo BR12345."
                    }
                },
                "required": ["order_id"],
                "additionalProperties": False
            }
        }
    }
]


def get_order_status(order_id: str) -> Dict[str, Any]:
    """
    Simulação de consulta real.
    Em produção, consulte banco de dados, ERP, gateway logístico ou API interna.
    """
    fake_database = {
        "BR12345": {
            "status": "em_transporte",
            "previsao_entrega": "2026-05-14",
            "transportadora": "Entrega Express"
        },
        "BR99999": {
            "status": "aguardando_pagamento",
            "previsao_entrega": None,
            "transportadora": None
        }
    }

    return fake_database.get(order_id, {
        "status": "nao_encontrado",
        "previsao_entrega": None,
        "transportadora": None
    })


def validate_arguments(args: Dict[str, Any]) -> str:
    """
    Validação mínima. Em produção, use uma biblioteca como Pydantic,
    regras de permissão e validação de usuário autenticado.
    """
    order_id = args.get("order_id")

    if not isinstance(order_id, str):
        raise ValueError("order_id deve ser uma string.")

    if not order_id.startswith("BR"):
        raise ValueError("order_id inválido.")

    return order_id


messages = [
    {
        "role": "system",
        "content": (
            "Você é um assistente de atendimento de e-commerce. "
            "Quando precisar consultar um pedido, use a ferramenta disponível."
        )
    },
    {
        "role": "user",
        "content": "Você pode verificar o status do meu pedido BR12345?"
    }
]

first_response = client.chat.completions.create(
    model="deepseek-v4-flash",
    messages=messages,
    tools=tools,
    tool_choice="auto",
    extra_body={
        "thinking": {"type": "disabled"}
    }
)

assistant_message = first_response.choices[0].message
messages.append(assistant_message)

if assistant_message.tool_calls:
    for tool_call in assistant_message.tool_calls:
        function_name = tool_call.function.name

        if function_name != "get_order_status":
            raise ValueError(f"Função não permitida: {function_name}")

        try:
            raw_args = tool_call.function.arguments
            parsed_args = json.loads(raw_args)
            order_id = validate_arguments(parsed_args)

            result = get_order_status(order_id)

        except Exception as error:
            result = {
                "error": True,
                "message": str(error)
            }

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

    final_response = client.chat.completions.create(
        model="deepseek-v4-flash",
        messages=messages,
        tools=tools,
        extra_body={
            "thinking": {"type": "disabled"}
        }
    )

    print(final_response.choices[0].message.content)
else:
    print(assistant_message.content)

Observe três pontos importantes nesse exemplo:

1. A chave DEEPSEEK_API_KEY fica em variável de ambiente, não no frontend.
2. O backend valida o nome da função e os argumentos antes de executar qualquer coisa.
3. O resultado da função é enviado de volta com role="tool" e o mesmo tool_call_id.

---

Exemplo com Node.js e TypeScript

O exemplo abaixo usa fetch para mostrar claramente o payload HTTP. Isso facilita entender o fluxo mesmo que você use outro framework, como Express, Fastify, NestJS ou Next.js API Routes.

type ToolCall = {
  id: string;
  type: "function";
  function: {
    name: string;
    arguments: string;
  };
};

type OrderStatus = {
  status: string;
  previsao_entrega: string | null;
  transportadora: string | null;
};

const DEEPSEEK_API_KEY = process.env.DEEPSEEK_API_KEY;

if (!DEEPSEEK_API_KEY) {
  throw new Error("DEEPSEEK_API_KEY não configurada.");
}

const tools = [
  {
    type: "function",
    function: {
      name: "get_order_status",
      description:
        "Consulta o status de um pedido pelo ID quando o usuário pede informações de entrega.",
      parameters: {
        type: "object",
        properties: {
          order_id: {
            type: "string",
            description: "ID do pedido, por exemplo BR12345."
          }
        },
        required: ["order_id"],
        additionalProperties: false
      }
    }
  }
];

function getOrderStatus(orderId: string): OrderStatus {
  const orders: Record<string, OrderStatus> = {
    BR12345: {
      status: "em_transporte",
      previsao_entrega: "2026-05-14",
      transportadora: "Entrega Express"
    }
  };

  return orders[orderId] ?? {
    status: "nao_encontrado",
    previsao_entrega: null,
    transportadora: null
  };
}

function validateOrderId(value: unknown): string {
  if (typeof value !== "string") {
    throw new Error("order_id deve ser string.");
  }

  if (!/^BR\d{5,}$/.test(value)) {
    throw new Error("Formato de order_id inválido.");
  }

  return value;
}

async function callDeepSeek(payload: unknown) {
  const response = await fetch("https://api.deepseek.com/chat/completions", {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${DEEPSEEK_API_KEY}`
    },
    body: JSON.stringify(payload)
  });

  if (!response.ok) {
    throw new Error(`Erro na API DeepSeek: ${response.status}`);
  }

  return response.json();
}

async function main() {
  const messages: any[] = [
    {
      role: "system",
      content:
        "Você é um assistente de atendimento. Use ferramentas apenas quando precisar consultar sistemas internos."
    },
    {
      role: "user",
      content: "Qual é o status do pedido BR12345?"
    }
  ];

  const first = await callDeepSeek({
    model: "deepseek-v4-flash",
    messages,
    tools,
    tool_choice: "auto",
    thinking: { type: "disabled" }
  });

  const assistantMessage = first.choices[0].message;
  messages.push(assistantMessage);

  const toolCalls: ToolCall[] | undefined = assistantMessage.tool_calls;

  if (toolCalls?.length) {
    for (const toolCall of toolCalls) {
      if (toolCall.function.name !== "get_order_status") {
        throw new Error(`Função não permitida: ${toolCall.function.name}`);
      }

      const args = JSON.parse(toolCall.function.arguments);
      const orderId = validateOrderId(args.order_id);
      const result = getOrderStatus(orderId);

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

    const final = await callDeepSeek({
      model: "deepseek-v4-flash",
      messages,
      tools,
      thinking: { type: "disabled" }
    });

    console.log(final.choices[0].message.content);
  } else {
    console.log(assistantMessage.content);
  }
}

main().catch(console.error);

Esse padrão pode ser adaptado para consultas a CRM, ERP, gateways de pagamento, sistemas de agenda, plataformas de suporte ou APIs internas.

---

Como usar tool_choice

O parâmetro tool_choice controla o comportamento do modelo em relação às ferramentas. A documentação oficial define quatro cenários principais: none, auto, required e forçar uma ferramenta específica por nome.

auto

Permite que o modelo decida entre responder normalmente ou chamar uma ferramenta.

{
  "tool_choice": "auto"
}

Use quando a pergunta pode ou não exigir dados externos. Exemplo: “Explique a política de troca” pode ser respondido sem ferramenta; “Consulte meu pedido” exige ferramenta.

none

Impede que o modelo chame ferramentas.

{
  "tool_choice": "none"
}

Use quando você quer apenas resposta textual, resumo, explicação, classificação ou brainstorming.

required

Obriga o modelo a chamar uma ou mais ferramentas.

{
  "tool_choice": "required"
}

Use com cuidado. É útil quando o fluxo exige sempre validação externa, como verificar elegibilidade, consultar disponibilidade ou confirmar status de pagamento.

Forçar uma função específica

Você também pode forçar o modelo a chamar uma função definida.

{
  "tool_choice": {
    "type": "function",
    "function": {
      "name": "get_order_status"
    }
  }
}

Use quando o fluxo da aplicação já sabe exatamente qual ferramenta deve ser usada. Por exemplo, em uma tela de pedido, toda pergunta do usuário pode estar vinculada ao mesmo pedido.

---

Strict mode com JSON Schema

O strict mode ajuda a reduzir saídas fora do formato esperado. Quando ativado, a API tenta fazer com que a chamada de ferramenta siga o JSON Schema da função. A documentação oficial descreve essa funcionalidade como Beta e informa três requisitos: usar base_url="https://api.deepseek.com/beta", definir strict: true em todas as funções dentro de tools e passar um JSON Schema aceito pelo servidor.

Exemplo:

{
  "type": "function",
  "function": {
    "name": "create_support_ticket",
    "strict": true,
    "description": "Cria um ticket de suporte para um cliente autenticado.",
    "parameters": {
      "type": "object",
      "properties": {
        "customer_id": {
          "type": "string",
          "description": "ID interno do cliente."
        },
        "priority": {
          "type": "string",
          "description": "Prioridade do ticket.",
          "enum": ["baixa", "media", "alta"]
        },
        "summary": {
          "type": "string",
          "description": "Resumo curto do problema."
        }
      },
      "required": ["customer_id", "priority", "summary"],
      "additionalProperties": false
    }
  }
}

Em produção, strict mode é útil, mas não elimina a necessidade de validação no backend. Você ainda precisa verificar permissões, autenticação, limites de taxa, regras de negócio e consistência dos dados.

Uma boa prática é combinar:

• strict: true
• additionalProperties: false
• campos required
• enum para valores fechados
• validação com Zod, Pydantic, Joi ou outra biblioteca no backend

---

Tool Calls em Thinking Mode

Thinking Mode é o modo em que o modelo pode produzir conteúdo de raciocínio interno por meio de reasoning_content, separado da resposta final em content. A documentação oficial informa que, em Thinking Mode, parâmetros como temperature, top_p, presence_penalty e frequency_penalty não são suportados ou não têm efeito, mesmo que sejam enviados por compatibilidade.

A parte mais importante para Tool Calls é esta: quando o modelo realiza uma chamada de ferramenta em Thinking Mode, o reasoning_content da mensagem intermediária precisa ser totalmente passado de volta à API em solicitações subsequentes. Se isso não for feito corretamente, a documentação informa que a API pode retornar erro 400.

Isso não significa que você deve mostrar o raciocínio interno ao usuário final. A prática recomendada é:

• preservar reasoning_content internamente quando necessário;
• não exibir chain-of-thought no frontend;
• enviar de volta o histórico correto para a API;
• usar non-thinking mode em fluxos simples e operacionais;
• usar Thinking Mode quando o agente precisa planejar, comparar opções ou executar várias etapas.

Para consultas simples, como “qual o status do pedido?”, o modo non-thinking pode ser suficiente. Para agentes que precisam consultar estoque, comparar datas, criar ticket, priorizar problema e responder com instruções, Thinking Mode pode ajudar.

---

Segurança: o modelo propõe, o backend decide

A frase mais importante de toda implementação é:

O modelo propõe. O backend decide.

Tool Calls não deve ser tratado como autorização automática para executar ações. Um modelo pode sugerir uma função correta com argumentos incorretos, chamar uma ferramenta em um momento inadequado ou tentar usar dados que o usuário não tem permissão para acessar.

Práticas essenciais de segurança

Prática	Por que importa
Allowlist de funções	O backend só deve aceitar funções explicitamente permitidas.
Validação de schema	Confirme tipos, formatos e campos obrigatórios.
Validação de permissões	Verifique se o usuário pode executar a ação.
Rate limits	Evite abuso, loops e chamadas excessivas.
Logs e auditoria	Registre chamadas, resultados e erros para investigação.
Confirmação do usuário	Exija confirmação antes de ações sensíveis.
Não executar comandos livres	Nunca transforme argumentos do modelo em comandos shell sem controle.
Não confiar cegamente em argumentos	O modelo pode gerar JSON inválido ou parâmetros não previstos.
Não colocar API key no frontend	A chave da DeepSeek deve ficar no servidor.

A própria documentação oficial alerta que os argumentos gerados pelo modelo podem não ser JSON válido e podem incluir parâmetros não definidos no schema, reforçando a necessidade de validação no código antes da execução.

Exemplo de ação sensível: cancelar pedido, alterar endereço, emitir reembolso, apagar registro, enviar e-mail em nome do usuário ou criar cobrança. Para esses casos, peça confirmação explícita e registre tudo.

---

Casos de uso ideais

DeepSeek Tool Calls é especialmente útil quando a resposta depende de dados atualizados ou de ações em sistemas externos.

Atendimento ao cliente

Um assistente pode consultar status de pedido, política aplicável, histórico de atendimento e abrir ticket se necessário.

Exemplo:

• get_order_status
• create_support_ticket
• get_return_policy

E-commerce

A aplicação pode verificar estoque, prazo de entrega, preço atualizado, cupom disponível e status de pagamento.

Exemplo:

• check_inventory
• calculate_shipping
• get_payment_status

CRM e vendas

Um agente pode buscar dados de cliente, registrar interação, sugerir próximo passo e criar uma tarefa para o vendedor.

Exemplo:

• get_customer_profile
• log_crm_interaction
• schedule_follow_up

Suporte técnico

Um bot pode consultar status de serviço, abrir incidente, classificar prioridade e buscar artigos de ajuda.

Exemplo:

• get_service_status
• create_incident
• search_help_center

Agentes internos

Equipes podem criar agentes para consultar agenda, gerar relatórios, buscar dados internos e executar automações controladas.

Exemplo:

• check_calendar_availability
• generate_internal_report
• create_ops_task

---

Quando não usar Tool Calls

Tool Calls é poderoso, mas nem sempre necessário.

Evite usar quando:

• o usuário só precisa de uma explicação textual;
• JSON Output é suficiente para estruturar uma resposta;
• não existe função real para executar;
• o fluxo exige uma decisão humana obrigatória;
• a ação é sensível e você ainda não implementou permissões;
• uma busca RAG em documentos resolve o problema;
• o custo de chamar APIs externas é maior que o benefício;
• a aplicação não tem logs, auditoria ou fallback.

Um erro comum é tentar transformar toda resposta em Tool Call. Isso torna o sistema mais complexo, mais caro e mais sujeito a falhas. Use ferramentas quando elas realmente conectam o modelo a uma capacidade externa.

---

Erros comuns e como corrigir

Erro	Causa provável	Solução
Esquecer de retornar role="tool"	O backend executa a função, mas não devolve o resultado corretamente.	Envie uma mensagem com role="tool", tool_call_id e content.
Usar tool_call_id errado	A aplicação perde a referência da chamada.	Use exatamente o ID retornado em message.tool_calls.
Não validar argumentos	O modelo gerou JSON inválido ou campo inesperado.	Faça parse seguro e validação com schema no backend.
Schema amplo demais	A função aceita qualquer coisa.	Use required, enum, tipos específicos e additionalProperties: false.
Descrição ruim da função	O modelo não sabe quando usar a ferramenta.	Escreva descrições objetivas e específicas.
tool_choice mal configurado	O modelo chama ferramenta quando não deveria, ou não chama quando deveria.	Use auto, none, required ou função forçada conforme o fluxo.
Loop de chamadas	O agente continua chamando ferramentas sem parar.	Defina limite máximo de iterações e fallback.
Usar modelo ou alias antigo sem verificar	Dependência de nomes legacy.	Use nomes atuais como deepseek-v4-flash e deepseek-v4-pro, conforme a documentação atual.
Esquecer reasoning_content em Thinking Mode com tools	Histórico incompleto após tool call.	Preserve internamente a mensagem completa quando houver Tool Calls em Thinking Mode.
Colocar API key no frontend	Exposição de credencial.	Faça chamadas pelo backend e use variáveis de ambiente.

---

Boas práticas para produção

Antes de colocar DeepSeek Tool Calls em produção, use esta checklist técnica:

• Use nomes de funções claros, como get_order_status, check_inventory e create_support_ticket.
• Escreva descrições específicas, não genéricas.
• Mantenha schemas pequenos e objetivos.
• Use enum sempre que houver valores fechados.
• Use additionalProperties: false quando possível.
• Valide argumentos no backend, mesmo com strict mode.
• Implemente timeouts para chamadas externas.
• Use retries controlados, não infinitos.
• Defina limite máximo de tool calls por interação.
• Registre logs com usuário, função, argumentos validados e resultado.
• Não registre dados sensíveis sem necessidade.
• Crie fallback quando a ferramenta falhar.
• Teste prompts adversariais.
• Versione suas tools, especialmente em sistemas grandes.
• Separe ferramentas de leitura e ferramentas de escrita.
• Peça confirmação para ações sensíveis.
• Monitore custo, latência e taxa de erro.
• Revise periodicamente a documentação oficial, pois modelos, preços e parâmetros podem mudar.

A documentação oficial de Models & Pricing informa que preços são cobrados por 1M tokens e que tokens incluem unidades de texto como palavras, números e pontuação, então controle de uso é parte importante da operação em produção.

---

Arquitetura recomendada

Uma arquitetura segura para Tool Calls separa claramente o modelo, a aplicação e os serviços internos.

Usuário
  ↓
Aplicação / Frontend
  ↓
Backend da aplicação
  ↓
DeepSeek API
  ↓
Resposta com tool_calls
  ↓
Backend Validator
  ↓
Serviço interno / API / Banco de dados / CRM / ERP
  ↓
Resultado da função
  ↓
Mensagem role="tool" com tool_call_id
  ↓
DeepSeek API
  ↓
Resposta final
  ↓
Usuário

A recomendação é nunca deixar o modelo acessar diretamente banco de dados, shell, sistemas internos ou APIs sensíveis. O backend deve ser uma camada de controle. Ele recebe a proposta do modelo, valida, executa apenas o permitido e devolve um resultado sanitizado.

Em uma aplicação real, essa arquitetura pode incluir:

• autenticação do usuário;
• autorização por função;
• validação de argumentos;
• rate limit;
• logs;
• auditoria;
• observabilidade;
• fila para ações demoradas;
• confirmação humana em operações sensíveis.

---

Perguntas frequentes sobre DeepSeek Tool Calls

---

Conclusão

DeepSeek Tool Calls é um recurso essencial para transformar a API DeepSeek em uma camada prática de integração com sistemas reais. Ele permite que o modelo deixe de ser apenas um gerador de texto e passe a atuar como um coordenador de funções externas, sempre com o backend no controle.

A implementação correta depende de três princípios: declarar ferramentas com schemas claros, validar tudo antes de executar e devolver os resultados com o tool_call_id correto. Para produção, segurança, logs, permissões, rate limits e boas descrições de função são tão importantes quanto o código.

Quando usado corretamente, DeepSeek Tool Calls é uma base sólida para construir AI agents, assistentes de atendimento, automações internas, integrações com CRM, e-commerce, suporte técnico e fluxos operacionais com dados atualizados.