PT ▾
Obter chave de API

API de Modelos LLM para Agentes: Guia de Chamada de Funções

Um agente é um loop: o modelo escolhe uma ferramenta, seu código a executa, o resultado volta e o modelo decide o que fazer a seguir. Aqui está uma versão funcional desse loop, além dos limites e custos que você deve considerar.

Atualizado

Loop isométrico de uma esfera passando por blocos de ferramentas ao redor de um terminal central, ilustrando um fluxo de trabalho de agente
01

Pontos principais

  • O endpoint suporta ferramentas, tool_choice, tool_calls em streaming e resultados de ferramentas com role.
  • Limite seu loop, valide os argumentos das ferramentas e faça retentativas para respostas 429 com uma breve pausa.
  • Mantenha os workers paralelos em ou abaixo de 8 por chave completa; streams mantêm o slot até o fim.
  • Uma execução de agente de seis passos com contexto crescente custa cerca de meio centavo.

O que um agente precisa da API

Se você está escolhendo uma API de modelos LLM para agentes, a lista de verificação é menor do que o marketing sugere. Você precisa de chamada de funções confiável, uma janela de contexto grande o suficiente para manter o histórico, limites de requisições previsíveis e um preço que não penalize um loop que faz muitas chamadas.

Esta API cobre esses pontos por meio da interface padrão OpenAI. Ela suporta tools e tool_choice, retorna tool_calls em respostas normais e em streaming, e aceita resultados de ferramentas como mensagens de ferramenta com role: "tool". O modo JSON está disponível por meio de response_format. A janela de contexto é de 100.000 tokens para prompt mais conclusão, e o ID do modelo é uncensored.

Como o lado do framework é apenas o cliente OpenAI, a maioria das bibliotecas de agentes que permitem definir uma URL base funcionará. Você as aponta para https://api.llmmodelsapi.com/v1, fornece sua chave e nomeia o modelo. Detalhes de configuração estão na documentação, e você pode obter uma chave na página de chave.

Dois limites moldam o design. Primeiro, o modelo é apenas texto, então qualquer manipulação de imagem, áudio ou arquivo deve acontecer nas suas ferramentas e voltar como texto. Segundo, não há embeddings neste endpoint, então se seu agente faz recuperação, a busca vetorial precisa de outra fonte.

Um prompt de sistema que mantém o loop estável

A maioria das falhas de agentes vem de instruções vagas, não da API. Um bom prompt de sistema diz ao modelo quem ele é, quais ferramentas existem, quando parar e qual formato a resposta final deve ter. Aqui está um para um assistente de pesquisa.

Você é um assistente de pesquisa. Você pode chamar as ferramentas search_notes e read_note. Chame uma ferramenta apenas quando precisar de informações que você já não tem. Use no máximo cinco chamadas de ferramentas. Quando tiver informações suficientes, responda com uma resposta curta e liste os IDs das notas que você usou. Se as notas não contiverem a resposta, diga isso claramente.

Observe o que ele faz. Ele nomeia as ferramentas, define um orçamento de chamadas, define a condição de parada e dá permissão ao modelo para dizer que não sabe. Essa última parte é importante, porque um agente forçado a responder inventará algo.

Defina uma temperatura baixa para uso de ferramentas. Valores em torno de 0,2 a 0,4 mantêm os nomes das ferramentas e os formatos de argumento estáveis. Se seu agente também escreve texto criativo no final, você pode aumentar a temperatura apenas para essa chamada final. O parâmetro seed é passado adiante, o que ajuda quando você quer reproduzir uma execução durante a depuração.

Para agentes de ficção adulta e roleplay, o mesmo padrão funciona: coloque a persona, as regras da cena e as ferramentas na mensagem do sistema. O modelo é ajustado para responder sem recusas de conteúdo para uso adulto lícito. Conteúdo sexual envolvendo menores permanece fora dos limites.

Um loop de agente mínimo em Python

O loop abaixo tem uma ferramenta, uma consulta em um dicionário que representa seus dados reais. Ele para quando o modelo responde sem uma chamada de ferramenta, ou após um número fixo de etapas.

import json
from openai import OpenAI

client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY")

NOTES = {
    "n1": "Invoice 114 was paid on March 3.",
    "n2": "Invoice 115 is overdue by 12 days.",
}

def search_notes(query):
    return [{"id": k, "text": v} for k, v in NOTES.items() if query.lower() in v.lower()]

TOOLS = [{
    "type": "function",
    "function": {
        "name": "search_notes",
        "description": "Search internal notes by keyword",
        "parameters": {
            "type": "object",
            "properties": {"query": {"type": "string"}},
            "required": ["query"],
        },
    },
}]

SYSTEM = "You are a research assistant. Use search_notes when needed, at most five calls. Then answer briefly."

def run(question, max_steps=6):
    messages = [
        {"role": "system", "content": SYSTEM},
        {"role": "user", "content": question},
    ]
    for step in range(max_steps):
        resp = client.chat.completions.create(
            model="uncensored",
            messages=messages,
            tools=TOOLS,
            temperature=0.3,
            max_tokens=500,
        )
        msg = resp.choices[0].message
        messages.append(msg)
        if not msg.tool_calls:
            return msg.content
        for call in msg.tool_calls:
            try:
                args = json.loads(call.function.arguments)
                result = search_notes(args["query"])
            except Exception as exc:
                result = {"error": str(exc)}
            messages.append({
                "role": "tool",
                "tool_call_id": call.id,
                "content": json.dumps(result),
            })
    return "Stopped: step limit reached."

print(run("Which invoice is overdue?"))

Três detalhes merecem atenção. O limite de etapas impede que um modelo confuso entre em loop até que seu orçamento acabe. O bloco try transforma uma string de argumento malformada em uma mensagem de erro que o modelo pode ler e corrigir. E cada resultado de ferramenta é enviado de volta com o tool_call_id correspondente, que é como o modelo sabe a qual chamada cada resposta pertence.

Tratamento de respostas 429 e concorrência

Agentes são irregulares. Um planejador pode distribuir cinco subtarefas de uma vez, e cada uma executa seu próprio loop. É aí que os limites de requisições aparecem.

Uma chave completa permite 8 requisições simultâneas e 300 requisições por minuto. Uma chave de teste permite 2 e 60. Após o limite, a API responde com HTTP 429. O código de erro indica qual limite você atingiu: rate_limited para requisições por minuto, concurrency para muitas ao mesmo tempo. Em sobrecarga temporária, você também recebe 429, com um cabeçalho Retry-After: 5.

Trate todos como recuperáveis. Aguarde o número de segundos no cabeçalho, ou alguns segundos se estiver ausente, e envie a solicitação novamente. Solicitações falhas não são cobradas, então as retentativas não custam nada. Um pequeno wrapper faz o trabalho.

import time
from openai import OpenAI, RateLimitError

client = OpenAI(base_url="https://api.llmmodelsapi.com/v1", api_key="YOUR_KEY", max_retries=0)

def chat_with_retry(**kwargs):
    for attempt in range(5):
        try:
            return client.chat.completions.create(model="uncensored", **kwargs)
        except RateLimitError as err:
            wait = 5
            if err.response is not None:
                wait = int(err.response.headers.get("retry-after", 5))
            time.sleep(wait)
    raise RuntimeError("Still rate limited after 5 attempts")

Para evitar o 429 desde o início, limite seu pool de workers. Um semáforo de 8 corresponde à chave completa. Se você transmitir respostas para uma interface de usuário, lembre-se de que uma stream mantém seu slot de concorrência até o último token chegar, então um cliente lento lendo uma resposta longa ocupa um slot o tempo todo. Ler os cabeçalhos X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency permite que seu código se adapte à chave que está usando.

Contexto, memória e custo de uma execução

Cada etapa do loop reenvia o histórico completo. É assim que APIs de chat funcionam, e isso significa que tokens de entrada crescem com cada chamada de ferramenta. Considere uma execução de seis passos onde o prompt começa com 2.000 tokens e cresce 1.000 por etapa, com 300 tokens de saída por etapa.

  • Tokens de entrada: 2.000 + 3.000 + 4.000 + 5.000 + 6.000 + 7.000 = 27.000
  • Tokens de saída: 6 x 300 = 1.800
  • Custo de entrada: 27.000 x 0,15 / 1.000.000 = $0,00405
  • Custo de saída: 1.800 x 0,50 / 1.000.000 = $0,0009
  • Total: $0,00495 por execução

Mil dessas execuções custam $4,95. Isso é barato o suficiente para permitir que um agente pense em várias etapas, mas o crescimento vale a pena ser monitorado. Com 100.000 tokens de espaço, um agente de longa execução eventualmente preencherá a janela, e um prompt desse tamanho custará 100.000 x 0,15 / 1.000.000 = $0,015 de entrada em cada etapa.

Três hábitos mantêm isso sob controle. Truncar resultados grandes de ferramentas antes de inseri-los no histórico, por exemplo, os primeiros 2.000 caracteres de uma página web. Resumir etapas antigas em uma única mensagem curta quando o histórico ultrapassar um limite. E armazenar fatos duráveis em seu próprio banco de dados em vez de confiar na conversa como memória.

O cabeçalho X-Balance-USD em cada resposta mostra o crédito restante, para que um supervisor de agente possa parar uma execução quando o saldo cair abaixo de um piso. O crédito é pré-pago a partir de $20 e nunca expira. Veja a página de preços para bônus de recarga.

Limites honestos para planejar em torno

Agentes construídos em qualquer modelo precisam de barreiras, e este não é exceção. Esteja pronto para o seguinte.

  • Argumentos malformados. O modelo pode produzir argumentos de ferramenta que não são JSON válido ou faltam um campo obrigatório. Analise defensivamente e retorne o erro como resultado da ferramenta.
  • Escolha errada de ferramenta. Escreva descrições curtas e distintas para as ferramentas. Se duas ferramentas soarem semelhantes, o modelo as confundirá. Use tool_choice para forçar uma chamada específica quando o fluxo exigir.
  • Apenas texto. Sem entrada ou saída de imagem, sem áudio, sem embeddings, sem fine-tuning. Faça essas partes em outro lugar e passe o resultado como texto.
  • Modelo único. Há um único modelo de pesos abertos por trás do endpoint, não um roteador entre fornecedores. Você não pode escolher um modelo menor para etapas simples.
  • Ferramentas destrutivas. Não dê a um agente uma ferramenta de exclusão ou pagamento sem uma etapa de confirmação em seu próprio código.

Agentes de planejamento também se beneficiam de uma segunda passagem. Após o loop retornar uma resposta, você pode fazer mais uma chamada barata que pede ao modelo para verificar a resposta contra os resultados das ferramentas que ele viu, usando o modo JSON para retornar um veredito e uma lista de afirmações não suportadas. Isso adiciona algumas centenas de tokens e captura a falha mais comum, que é uma resposta confiante que ignora o que as ferramentas retornaram.

Finalmente, registre cada etapa. Armazene as mensagens, os argumentos da ferramenta e o cabeçalho X-Request-Id de cada resposta. Quando uma execução falha, o ID da requisição permite apontar para a chamada exata, e o histórico registrado mostra qual resultado de ferramenta enganou o modelo. Agentes são mais fáceis de melhorar quando você pode reproduzir uma execução ruim e alterar uma coisa de cada vez.

Teste um agente com a chave de teste antes de se comprometer. Novos usuários podem reivindicar $0,50 de crédito, que na execução de seis passos acima cobre cerca de 101 execuções completas (0,50 / 0,00495). Mantenha em mente as 2 requisições simultâneas da chave de teste e execute um agente por vez. Para uma visão mais ampla do serviço, leia a visão geral de pagamento por token. Os prompts não são usados para treinamento.

02

Perguntas e respostas

A API suporta chamada de funções para agentes?

Sim. Aceita ferramentas e tool_choice, retorna tool_calls (também quando streaming) e aceita resultados como mensagens com role tool.

Quantas chamadas de agente podem ser executadas em paralelo?

Uma chave completa permite 8 requisições simultâneas e 300 por minuto. Uma chave de teste permite 2 simultâneas e 60 por minuto.

O que um agente deve fazer quando ele recebe um 429?

Aguarde o valor Retry-After ou alguns segundos se não houver, e tente novamente. Requisições rejeitadas não são cobradas.

O agente consegue processar imagens ou áudio?

Não. O modelo funciona com texto apenas, então qualquer outra mídia deve ser processada pelas suas próprias ferramentas e passada em como texto.

Sua chave está a um formulário de distância

Crie uma conta, copie a chave e altere a URL base. Essa é toda a configuração.

Obter chave de API