agent-hub-llm-sdk

SDK genérico para executar LLMs com tool-calling local, compatível com qualquer API no formato OpenAI.

LLMs suportadas

| Provider | URL Base | API Key | Models sugeridos | |----------|----------|---------|-----------------| | Ollama | editável (local) | opcional | gemma4, llama3.1, qwen2.5-coder, deepseek-coder-v2, codestral | | LM Studio | editável (local) | opcional | qualquer modelo carregado no servidor | | Grok (xAI) | https://api.x.ai/v1 | obrigatória | grok-3, grok-3-mini, grok-2 | | OpenRouter | https://openrouter.ai/api/v1 | obrigatória | claude-sonnet-4, gemini-2.5-pro, llama-3.1-405b | | Groq | https://api.groq.com/openai/v1 | obrigatória | llama-3.3-70b-versatile, gemma2-9b-it, mixtral-8x7b | | DeepSeek | https://api.deepseek.com/v1 | obrigatória | deepseek-chat, deepseek-coder, deepseek-reasoner | | NVIDIA NIM | https://integrate.api.nvidia.com/v1 | obrigatória | meta/llama-3.3-70b-instruct, meta/llama-3.1-405b-instruct, meta/llama-3.1-70b-instruct, mistralai/mistral-medium-3.5-128b | | Custom | editável | opcional | qualquer modelo |

Qualquer API compatível com o formato OpenAI (/v1/chat/completions com tool calling) pode ser usada via Custom.

Como funciona

O SDK implementa um tool-calling loop local:

1. Monta o system prompt + tools e envia para a API
2. Se a resposta contém tool_calls, executa localmente
3. Devolve o resultado da tool para a API
4. Repete até a API retornar a resposta final (sem tool calls)

Tools disponíveis

| Tool | Descrição | |------|-----------| | read_file | Lê arquivo com numeração de linhas | | write_file | Cria ou sobrescreve arquivo | | edit_file | Substituição exata de string em arquivo | | run_bash | Executa comando shell | | glob | Busca arquivos por padrão glob | | grep | Busca conteúdo em arquivos (regex) | | list_directory | Lista diretório |

Uso

import { runGeneric } from 'agent-hub-llm-sdk';

const result = await runGeneric({
  cwd: '/path/to/project',
  prompt: 'Leia o package.json e me diga a versão',
  agentFlags: ['--base-url', 'http://localhost:11434/v1', '-m', 'gemma4'],
});

console.log(result.answer);

Variáveis de ambiente

| Variável | Descrição | |----------|-----------| | GENERIC_BASE_URL | URL base da API | | GENERIC_MODEL | Modelo padrão | | GENERIC_API_KEY | API key |

As flags --base-url, -m/--model e --api-key têm prioridade sobre as variáveis de ambiente.

max_tokens

Limite de tokens gerados pelo modelo numa única resposta — soma de content + tool_calls + reasoning_content (em modelos que pensam). 1 token ≈ 3 caracteres em PT.

Default do SDK: 8192 (DEFAULT_MAX_TOKENS em src/client.js).

| Tipo de modelo | Sugestão | Exemplos | |---|---|---| | Conversacionais | 4096–8192 | Llama, Mistral, Qwen, Gemma, Claude | | Reasoning leves | 8192–16384 | Nemotron, R1-Distill | | Reasoning pesados | 16384–32768 | DeepSeek R1, GLM-4.7+, o1-style |

Sintoma de valor baixo demais em reasoning model: resposta vem vazia, com finish_reason: "length" — o modelo esgotou o orçamento gerando reasoning_content antes de chegar no content final.

Configurável por LLM no dashboard (campo "Max tokens por resposta") ou via runGeneric({ maxTokens: N }).

Testes

npm -w agent-hub-llm-sdk test