OpenAI

The OpenAI SDK covers GPT-4, GPT-4o, and the wider ecosystem of OpenAI-compatible endpoints. agentfootprint's openai() factory wraps it as an LLMProvider — same shape as anthropic() and mock().

Install

npm install openai

Peer dep, lazy-required, optional in peerDependenciesMeta. Friendly install hint at first call if missing.

Use

openai() is a vendor-SDK provider, so it lives at the agentfootprint/providers subpath (this keeps the lazy openai peer-dep require out of the main barrel). Agent comes from the main barrel as usual:

import { Agent } from 'agentfootprint';
import { openai } from 'agentfootprint/providers';

const provider = openai({
  apiKey: process.env.OPENAI_API_KEY!,
});

const agent = Agent.create({
  provider,
  model: 'gpt-4o',
}).build();

OpenAI-compatible endpoints (Ollama, llama.cpp, vLLM, Together, Groq, LM Studio)

Local models, self-hosted servers, and most inference clouds all speak the same Chat Completions shape OpenAI does. Point baseURL at any of them — no separate adapter, no new API to learn:

// llama.cpp's llama-server:  llama-server -m model.gguf --port 8080
const llamaCpp = openai({
  baseURL: 'http://localhost:8080/v1',
  apiKey: 'not-needed-for-local',   // local servers ignore it; the SDK just requires non-empty
  defaultModel: 'local-model',      // the model is whatever .gguf the server loaded
});

// vLLM:  vllm serve meta-llama/Llama-3.1-8B-Instruct --port 8000
const vllm = openai({
  baseURL: 'http://localhost:8000/v1',
  apiKey: 'not-needed-for-local',
  defaultModel: 'meta-llama/Llama-3.1-8B-Instruct',
});

// Groq (cloud, OpenAI-compatible — a real key is required)
const groq = openai({
  apiKey: 'YOUR_GROQ_API_KEY',
  baseURL: 'https://api.groq.com/openai/v1',
});

Any baseURL also switches the adapter into legacy-endpoint mode: it sends the older max_tokens field instead of max_completion_tokens, and skips stream_options (fields real OpenAI/Azure accept but many local servers and compatible clouds don't) — see OpenAIProviderOptions/legacyEndpoint in OpenAIProvider.ts. You don't configure this; it's automatic whenever baseURL is set.

For Ollama specifically, the convenience factory (also from agentfootprint/providers). It defaults baseURL to http://localhost:11434/v1 and names the provider ollama; set the model via defaultModel (or pass a custom host):

const provider = ollama({ defaultModel: 'llama3.1' });

$0 to iterate. Local inference costs nothing and needs no key — great for exploring. It's usually still the wrong choice for CI: slower, and small models are less reliable at tool-calling. Reach for mock() once you're past manual poking and writing tests.

Tools (function calling)

OpenAI's Chat Completions API has native function calling. The provider translates Tool[] into the API's tools format and round-trips assistant tool_calls.

Streaming

provider.stream(req) uses the SDK's native SSE streaming; tokens land as they arrive. Final chunk carries the full LLMResponse.

Browser variant

BrowserOpenAIProvider — fetch-based, zero peer deps. CORS depends on the endpoint; OpenAI requires the user-supplied key in the Authorization header, which the consumer must set explicitly.

Limitations

• Multi-modal not exposed yet (LLMMessage.content is string).
• responseFormat (JSON-mode) not exposed yet — pass schema instructions via systemPrompt.

Next steps

• Resilience — wrap with withRetry / withFallback
• Streaming — token-by-token UI rendering
• Ollama — local models via OpenAI-compatible endpoint