Models and prompts

Use Vercel AI SDK providers, choose a gateway or direct connection, and shape the agent’s instructions.

Cognitio uses Vercel AI SDK to connect to language models. Cognitio runs the agent loop, tools, and sessions; the bundled runtime resolves your model ID through an AI SDK provider adapter and streams the model’s response.

A model ID has the form provider/model, such as openai/gpt-4.1-mini. Changing providers requires that provider’s credentials and a model your account can access. You do not need to install an @ai-sdk/* package in your application for the bundled integrations below.

​

Providers and gateways

AI SDK is the model integration layer. It does not require a hosted gateway: openai/... and anthropic/... connect to their respective providers. You can instead choose a gateway such as OpenRouter or Vercel AI Gateway, or configure your own endpoint. Cognitio does not operate a hosted inference gateway, and requests do not automatically route through Vercel AI Gateway.

Expand a group to find a provider ID. Use that ID before the model name in model: "provider/model"; the models.* helpers cover only a convenience subset of these providers.

Direct and cloud providers

These integrations have provider adapters included in the runtime. Availability still depends on credentials, provider configuration, the runtime’s model catalog, and your account’s model access.

Provider	Provider ID
Amazon Bedrock	amazon-bedrock
Anthropic	anthropic
Azure OpenAI	azure
Azure Cognitive Services	azure-cognitive-services
Cerebras	cerebras
Cohere	cohere
DeepInfra	deepinfra
GitHub Copilot	github-copilot
GitLab Duo	gitlab
Google Gemini	google
Google Vertex AI	google-vertex
Google Vertex AI with Anthropic	google-vertex-anthropic
Groq	groq
Mistral	mistral
OpenAI	openai
Perplexity	perplexity
Together AI	togetherai
v0	v0
Venice AI	venice
xAI	xai

Cloud integrations can require a region, project, resource name, or deployment ID in addition to authentication. GitLab Duo uses provider-specific authentication; its instance URL defaults to https://gitlab.com and can be configured for another instance. GitHub Copilot requires a supported Copilot authentication flow, and a GitHub token is not implicitly forwarded to isolated runtimes. Perplexity here is a model provider; this does not select the runtime’s built-in web search provider.

Gateways

Gateway	Provider ID	Configuration
OpenRouter	openrouter	OPENROUTER_API_KEY and an available routed model.
Vercel AI Gateway	vercel	AI_GATEWAY_API_KEY and an available routed model.
Cloudflare AI Gateway	cloudflare-ai-gateway	Cloudflare account ID, gateway ID, and gateway authentication/configuration.

Gateway model names may contain another provider prefix. Keep the full provider-local model name after the first slash. The vercel ID selects Vercel AI Gateway; v0 selects the separate v0 model integration.

Forward gateway credentials explicitly with spawn.env or spawn.passEnv when using a local isolated runtime. For a remote runtime, configure credentials on the server. Selecting a gateway changes routing and billing; consult that gateway’s model and capability requirements.

OpenAI-compatible and custom providers

The runtime also includes an OpenAI-compatible adapter. The model catalog configures additional providers through that adapter, including:

Provider	Provider ID
Alibaba	alibaba, alibaba-cn
Cloudflare Workers AI	cloudflare-workers-ai
DeepSeek	deepseek
Fireworks AI	fireworks-ai
GitHub Models	github-models
Hugging Face	huggingface
LM Studio	lmstudio
Moonshot AI	moonshotai, moonshotai-cn
NVIDIA	nvidia
Ollama Cloud	ollama-cloud
Z.AI	zai
Zhipu AI	zhipuai

This is a selection of catalog integrations, not a list of every OpenAI-compatible service. Provider-specific authentication and endpoint setup still apply. Ollama Cloud is separate from a locally hosted Ollama endpoint.

Other catalog entries reuse different bundled adapters: MiniMax (minimax, minimax-cn) and Kimi for Coding (kimi-for-coding) use Anthropic-compatible integrations. The configured adapter and model metadata determine how each request is sent.

For local Ollama or another private OpenAI-compatible endpoint, define your own provider ID, base URL, credentials, and model metadata in spawn.config.provider, as described in Private providers and model catalogs.

The wider AI SDK ecosystem includes additional adapters. An adapter appearing in AI SDK’s documentation does not mean it is bundled or configured in Cognitio. Model features also vary: check tool calling, structured output, reasoning, and input modalities for the particular provider and model you select.

For local isolated runtimes, explicitly pass the credentials your integration needs through spawn.env or spawn.passEnv; only a reviewed subset of provider environment variables is inherited automatically. See Defaults and isolation. Remote runtimes resolve credentials on the server.

​

Choose a model and write instructions

Use the TypeScript example setup. This complete example uses an OpenAI model and application-specific instructions. It needs only OPENAI_API_KEY from your environment.

import { Agent, models } from "cognitio-agent-sdk"

const apiKey = process.env.OPENAI_API_KEY
if (!apiKey) throw new Error("Set OPENAI_API_KEY before running this example.")

const agent = new Agent({
  model: models.openai("gpt-4.1-mini"),
  instructions: "You explain technical concepts to a new developer. Use one short analogy and no jargon.",
  appendSystemPrompt: "Keep your answer under 80 words.",
  spawn: { env: { OPENAI_API_KEY: apiKey } },
  disallowedTools: ["*"],
  maxTurns: 1,
  maxBudgetUsd: 0.03,
})
try {
  const result = await agent.run("What does a database transaction do?", {
    signal: AbortSignal.timeout(60_000),
  })
  if (result.isError) throw new Error(`Agent ended: ${result.subtype}`)
  console.log(result.text)
} finally {
  await agent.close()
}

models.openai("gpt-4.1-mini") returns the string "openai/gpt-4.1-mini". Helpers such as models.anthropic(...) and models.google(...) give editor completions; they do not create provider clients, load credentials, or verify account access. Plain strings are accepted, including newly released or private model IDs, but the runtime still needs a configured provider and model definition.

To use another provider, change both the model and the credential you explicitly pass in spawn.env. For example, an Anthropic model uses ANTHROPIC_API_KEY; a Google model uses GEMINI_API_KEY. Never put a real key in source code or commit your .env file.

​

Understand prompt composition

With no custom prompt, the SDK supplies a neutral, general-purpose agent prompt. You do not need to replace it for every application.

Option	What it changes
instructions: "..."	Replaces the base system prompt with your application instructions.
systemPrompt: "..."	Also selects a full custom base prompt. Do not combine it with instructions.
appendSystemPrompt: "..."	Adds instructions after the chosen base prompt. Useful for output style or application conventions.
systemPrompt: { type: "preset", preset: "default", append: "..." }	Explicitly chooses the runtime’s coding-oriented prompt and appends your text.
systemPrompt: { type: "preset", preset: "none" }	Omits the preset base prompt. Other context channels remain independently controlled.
includeEnvironment: false	Omits the automatic working-directory/platform context from the system prompt.

instructions and systemPrompt are mutually exclusive. appendSystemPrompt can be used with either. The exported NEUTRAL_BASE_PROMPT lets you compose with the SDK’s exact neutral prompt when needed.

Instructions guide the model; they do not enforce authorization. Use tool policies and permissions for restrictions such as preventing shell commands or limiting file operations.

​

Project instructions and context

SDK sessions default to settingSources: [], so project/user/local instruction resources are not discovered automatically. Programmatic instructions and explicitly supplied tools still work. Opt into only the sources your application wants to load with settingSources: ["project"], "user", or "local" entries.

includeEnvironment: false does not remove text that you explicitly put in a prompt or return from a tool. Similarly, selecting preset: "none" does not disable skills, tool descriptions, or enabled instruction sources. These options control separate pieces of context.

​

Change the model for one run

A per-run model overrides the Agent’s default for that fresh session. The Agent keeps its original profile for later runs. On an existing idle Session, session.setModel(id) changes the model used for following turns; the conversation history stays in that session.

Choose models based on the task’s required capabilities: tool calling for agents that take actions, input modalities for image/file prompts, and supported schema behavior for structured output. An accepted model ID is not a promise that every capability is available on that model.

​

Reasoning controls

Leave reasoning controls unset for the gpt-4.1-mini examples on this site. For models that support reasoning, effort accepts "low", "medium", "high", or "max", subject to the model’s supported variants.

thinkingConfig accepts one of:

Value	Request
{ type: "adaptive" }	Let a supported provider/model determine its reasoning budget.
{ type: "enabled", budgetTokens: 4096 }	Request an explicit thinking budget. It must be at least 1024 and below the model’s output limit.
{ type: "disabled" }	Disable thinking through a provider integration that supports this control.

These are provider-specific capabilities. The runtime maps supported combinations to the provider’s options and rejects unsupported combinations explicitly. Even thinkingConfig: { type: "disabled" } is not a portable option for every provider; omit the field when the provider does not support it. Reasoning tokens and additional calls can affect latency and cost.

​

Private providers and model catalogs

For a private OpenAI-compatible endpoint, configure spawn.config.provider with its provider ID, adapter npm, options.baseURL, credentials, and model definitions/limits. Reference that provider as your-provider/your-model. The SpawnOptions reference describes the configuration entry point. Cognitio does not include a hosted inference gateway.

The runtime uses a validated model catalog for metadata such as limits and estimated prices. Advanced deployments can supply COGNITIO_MODELS_PATH for a local catalog, COGNITIO_DISABLE_MODELS_FETCH: "1" to disable automatic remote catalog fetching, or COGNITIO_MODELS_URL for a mirror base URL (the runtime appends /api.json). Supply these through spawn.env for an isolated child. A local path alone does not disable background refresh; unreadable/invalid-JSON files may fall back, while parsed catalog data that fails schema validation is rejected. An explicitly forced catalog refresh can still make a network request.