Connect VoltAgent

Give a VoltAgent agent an explicit OpenAI-compatible Chat Completions model.

AELDER · SERVICE BASE URL

https://aelder.dev/v1

LOCAL CONFIGURATION

Let my agent set this up

Copy this task to an agent already running on your computer. Enter your API key locally when asked.

Help me connect VoltAgent to AELDER using this guide: https://aelder.dev/docs/voltagent/
Service Base URL: https://aelder.dev/v1
First inspect my installed version, active profile and configuration. Explain any mismatch with the guide before changing anything.
Use the documented local configuration or CLI method. Do not automate the GUI, install software or change permissions without asking.
Preserve existing accounts, providers, models, defaults, permissions and unrelated settings. Propose the smallest change, show a redacted diff, and back up any files before editing.
Have me enter my API key locally using the tool's secret storage or an environment variable. Never ask me to paste a key into chat, print it, or include it in a command, diff, log or commit.
Use the exact model ID I choose from my account's model list. Do not invent model IDs or assume every model supports every API format or tool feature.
Validate syntax and configuration loading before making any generation request. If there is no dry-run, say so.
Explain any proposed paid test, the model and what it sends, and ask for approval before running it. Do not send project files or private conversation history as a test.
Finish with the settings changed, checks performed and steps to restore the backup.

VoltAgent accepts a Vercel AI SDK model object in its native Agent configuration. Use an explicit OpenAI-compatible provider to control the endpoint and protocol, rather than relying on its built-in provider registry.

This guide assumes an existing TypeScript VoltAgent project with @voltagent/core and a compatible @ai-sdk/openai-compatible package. Preserve the application’s tools, memory and server configuration.

1. Prepare local values

Set SERVICE_BASE_URL to the Base URL above, including /v1, and SERVICE_MODEL_ID to an exact ID from the authenticated models endpoint. Supply SERVICE_API_KEY privately through your process environment or secrets manager.

In Bash or Zsh, this prompt keeps the literal key out of shell history:

printf 'Service API key: '
IFS= read -r -s SERVICE_API_KEY
printf '\n'
export SERVICE_API_KEY

Run the project’s existing development or execution command from that environment. Keep the key in server-side code; do not expose it in browser bundles, tracked files or agent chats.

2. Pass the model to the agent

import { Agent } from "@voltagent/core";
import { createOpenAICompatible } from "@ai-sdk/openai-compatible";

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

const service = createOpenAICompatible({
  name: "my-api",
  baseURL: required("SERVICE_BASE_URL"),
  apiKey: required("SERVICE_API_KEY"),
});

const agent = new Agent({
  name: "Service assistant",
  instructions: "Answer briefly.",
  model: service.chatModel(required("SERVICE_MODEL_ID")),
});

chatModel selects Chat Completions at /v1/chat/completions. Do not put that full path in baseURL. The my-api name identifies the local provider; the HTTP request uses the exact model ID passed to chatModel, including any slashes.

To switch models, change SERVICE_MODEL_ID and recreate the model and agent. This explicit model object does not register or discover the service’s entire catalog in VoltAgent’s model router.

3. Verify separately

Type-checking the project and constructing the agent check local configuration. This call sends a billable request:

const result = await agent.generateText("Reply with OK.");
console.log(result.text);

Confirm the model and usage in the service dashboard. Tools, retries and multi-step agent runs can produce additional requests.

A text response does not establish streaming, tool calls, structured output, reasoning fields or image support. Test the capabilities your workflow needs and check compatible package versions. Do not use built-in registry prices or limits as evidence of this service’s billing or context window.

Sources: VoltAgent’s provider configuration and the AI SDK’s OpenAI-compatible provider. The native configuration was reviewed; a live service run has not been verified.

Need the key? Open your AELDER dashboard. For direct API calls, see the API reference.