Assistiu ao curso de agent e não consegue executar? Use uma única Key para pôr os exemplos a funcionar

Há um post no X a brincar: quem pagou 500 dólares por um curso de AI Agent agora pode ver de graça. Post original: https://x.com/deanwperkins/status/2116911546282733623 (autor Dean W. Perkins, @deanwperkins). O consenso na discussão é que o curso em si não é escasso; o que é escasso é pôr em funcionamento o que está no curso.

Essa frase acerta no ponto. Onde a maioria fica presa não é em não entender o ciclo do agent, é em não conseguir dar o primeiro passo: falta a Key do modelo usado no código de exemplo, troca-se de modelo e o protocolo já não bate certo, e se não funciona, não há como validar.

Este artigo fala da configuração mínima funcional, não de teoria de agents.

Um agent mínimo tem apenas três coisas

Deixando de lado frameworks e abstrações, um agent que faz trabalho é composto por três componentes:

1. Um modelo capaz de chamar ferramentas
2. Um conjunto de definições de ferramentas (nome, parâmetros, descrição)
3. Um ciclo: o modelo decide que ferramenta chamar, você executa e devolve o resultado ao modelo, até ele dizer que terminou

Aqueles multiagentes, memória e planeamento dos cursos são todos coisas adicionadas a estas três. Primeiro ponha estas três a funcionar.

Primeiro passo: preparar a Key

O primeiro trabalho da maioria dos cursos é «vá pedir a API Key de um determinado modelo». Esta etapa tem uma taxa de desistência elevada: registo, cartão, esperar aprovação, alguns ainda exigem pedir quota.

Usar uma entrada unificada salta esta etapa. A Key da HiAPI tem um único conjunto de autenticação e cobre modelos de texto como Claude, GPT, Kimi, Grok e DeepSeek, através do protocolo padrão Chat Completions.

Depois de obter a Key, confirme primeiro que funciona:

curl -s https://api.hiapi.ai/v1/chat/completions \
  -H "Authorization: Bearer YOUR_HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-6.1-sol",
    "messages": [{"role": "user", "content": "Diga uma saudação"}]
  }'

Se devolver conteúdo, a Key está bem.

Segundo passo: definir a ferramenta

A definição da ferramenta é o manual que se dá ao modelo. Ele precisa saber que ferramentas existem e que parâmetros cada uma exige.

tools = [{
    "type": "function",
    "function": {
        "name": "get_weather",
        "description": "Consultar o clima atual da cidade indicada",
        "parameters": {
            "type": "object",
            "properties": {
                "city": {"type": "string", "description": "Nome da cidade, ex.: Pequim"}
            },
            "required": ["city"]
        }
    }
}]

A explicação a escrever é só uma frase: o modelo baseia-se na description para decidir quando deve usar esta ferramenta. Quanto mais clara, menor a probabilidade de erro na chamada.

Terceiro passo: escrever o ciclo

import json, requests

API = "https://api.hiapi.ai/v1/chat/completions"
KEY = "YOUR_HIAPI_API_KEY"
HEADERS = {"Authorization": f"Bearer {KEY}", "Content-Type": "application/json"}

def run_weather(city):
    return {"city": city, "temp": 18, "condition": "ensolarado"}  # implementação de exemplo

messages = [{"role": "user", "content": "Quantos graus faz hoje em Pequim?"}]

for _ in range(5):  # evitar ciclo infinito
    resp = requests.post(API, headers=HEADERS, json={
        "model": "gpt-6.1-sol",
        "messages": messages,
        "tools": tools,
    }).json()

    msg = resp["choices"][0]["message"]
    messages.append(msg)

    if not msg.get("tool_calls"):
        print(msg["content"])
        break

    for call in msg["tool_calls"]:
        args = json.loads(call["function"]["arguments"])
        result = run_weather(args["city"])
        messages.append({
            "role": "tool",
            "tool_call_id": call["id"],
            "content": json.dumps(result, ensure_ascii=False),
        })

Ao executar isto, verá que o modelo decide primeiro chamar get_weather, e depois de receber o resultado o organiza numa frase de resposta. Este é o ciclo completo do agent.

Como escolher o modelo

Com o mesmo ciclo, basta mudar o campo model para trocar de modelo. A diferença de custo é enorme:

Modelo	Entrada	Saída	Indicado para
GPT-6 Luna	$0.025	$0.125	Chamadas simples de ferramentas, classificação, extração
GPT-6.1 Terra	$0.25	$1.25	Agents do dia a dia, tarefas de código
GPT-6.1 Sol	$0.50	$2.50	Tarefas complexas de vários passos
Claude Opus 5.5	$2.02	$10.08	Tarefas longas, que exigem raciocínio profundo

Um ciclo de chamada de ferramenta gasta cerca de alguns milhares de tokens; no modelo mais barato, o Luna, uma vez custa menos de um décimo de cêntimo. Para fazer experiências com o curso, o custo é negligenciável.

Se o curso indicar um modelo específico, use o do curso; se o curso não indicar ou não puder usá-lo, usar um substituto do mesmo nível não afeta o resultado da aprendizagem, porque a lógica do ciclo é a mesma.

Os três pontos onde é mais fácil ficar preso no curso

O formato de retorno da chamada de ferramentas está errado. Diferentes fornecedores de modelos organizam os campos de tool_calls de forma distinta. Com modelos que seguem o protocolo compatível com Chat Completions, o formato é unificado e não é preciso alterar o código de análise ao trocar de modelo.

O contexto cresce cada vez mais. Levar todo o histórico em cada ronda faz com que, à trigésima ronda, se atinja o limite. Os cursos avançados falam de estratégias de corte; por agora, basta saber que este obstáculo existe.

O modelo não chama ferramentas e só responde com texto. Normalmente é porque a descrição da ferramenta está demasiado vaga, ou o prompt não deixa claro «tens ferramentas disponíveis». Torne a descrição mais concreta, ou indique-o no prompt de sistema.

O que fazer depois de funcionar

Não se precipite para os frameworks.

Depois de o ciclo mínimo funcionar, acrescente estas coisas por ordem:

1. Adicionar tratamento de erros: quando a execução da ferramenta falha, devolver a informação do erro ao modelo, para que ele tente de novo ou mude de caminho
2. Adicionar estatísticas de utilização: registar o número de tokens de cada chamada, para saber onde o custo é gasto
3. Adicionar timeout e retry: falhas de rede são a norma
4. Só depois considerar frameworks: se a tarefa for complexa ao ponto de precisar de multiagentes ou máquinas de estado complexas, aí sim, usar um framework

A arquitetura ensinada nos cursos é normalmente orientada para produção; montá-la diretamente tende a bloquear logo no primeiro passo. Ponha primeiro os três componentes a funcionar e acrescente o resto conforme a necessidade.

Perguntas frequentes

É obrigatório usar um modelo específico?

Não. Desde que suporte chamada de ferramentas (function calling), a lógica do ciclo é universal. Quando o modelo indicado pelo curso não estiver disponível, um substituto do mesmo preço não afeta a compreensão.

Qual é a diferença entre cursos gratuitos e pagos?

Segundo a discussão no X, a diferença está mais na estrutura e no esclarecimento de dúvidas do que no conhecimento em si. Pôr os exemplos a funcionar é algo que ambos os lados têm de fazer por si.

As ferramentas podem chamar APIs reais?

Podem. Basta substituir run_weather por um pedido HTTP real. Tenha atenção para apanhar todas as exceções na função da ferramenta, caso contrário uma falha quebra todo o ciclo.

Quanto custa uma execução?

O exemplo mínimo gasta alguns milhares de tokens; no modelo mais barato, uma vez custa menos de um décimo de cêntimo, e nos caros apenas alguns cêntimos. Para fazer experiências, não há que preocupar com o custo.

Conclusões principais

O obstáculo dos cursos de agent nunca é a teoria, é o primeiro exemplo que não funciona. Três coisas bastam para pôr um ciclo completo a funcionar: uma Key utilizável, uma definição de ferramenta e um ciclo que devolve os resultados ao modelo. Depois de funcionar, acrescentar detalhes de engenharia é dez vezes mais fácil do que ao contrário.

Ver modelos de texto disponíveis e preços

---

Fontes

• Origem do tema: Dean W. Perkins (@deanwperkins), https://x.com/deanwperkins/status/2116911546282733623
• O post não inclui link para nenhum curso específico; este artigo não aponta para nenhum curso em particular, apenas descreve a configuração genérica para pôr os exemplos a funcionar
• Os exemplos de código e os dados de preços são compilados por este site; os preços são do ambiente de produção da HiAPI (2026-11-02)