> ## Documentation Index
> Fetch the complete documentation index at: https://cognitio-agent.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](https://ai-sdk.dev/docs/foundations/providers-and-models) 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.

> [accordion] 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.

> [accordion] 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.

> [accordion] 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](#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](https://cognitio-agent.mintlify.site/defaults-and-isolation.md). Remote runtimes resolve credentials on the server.

## Choose a model and write instructions

Use the [TypeScript example setup](https://cognitio-agent.mintlify.site/concepts/agents.md#run-the-examples). This complete example uses an OpenAI model and application-specific instructions. It needs only `OPENAI_API_KEY` from your environment.

```ts theme={null}
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](https://cognitio-agent.mintlify.site/concepts/permissions.md) 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](https://cognitio-agent.mintlify.site/concepts/structured-output.md). 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](https://cognitio-agent.mintlify.site/api-reference/interfaces/SpawnOptions.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.