Mohamed BoudraandGitHub
7954babca6
* feat(client): publish the TypeScript SDK surface Make the high-level client API usable for external integrations and document complete agent, workspace, provider, event, and recipe flows. * fix(client): correlate provider snapshots by daemon cwd Return the daemon's canonical snapshot identity so waitForReady can match updates for relative, tilde, and otherwise non-canonical paths without duplicating filesystem rules in the SDK. * test(server): make snapshot cwd assertion portable * fix(client): gate canonical provider snapshot waits Older daemons do not expose the canonical snapshot identity needed to correlate workspace updates safely. Require the advertised capability and fail with an update-host message instead of guessing across workspaces.
115 lines
3.5 KiB
Markdown
115 lines
3.5 KiB
Markdown
---
|
|
title: Providers with the SDK
|
|
description: Select a provider and model, discover available configurations, and configure an agent session.
|
|
nav: Providers
|
|
order: 54
|
|
category: TypeScript SDK
|
|
---
|
|
|
|
# Providers with the SDK
|
|
|
|
Every agent configuration names both the provider and model:
|
|
|
|
```ts
|
|
config: {
|
|
provider: "codex/gpt-5.5",
|
|
}
|
|
```
|
|
|
|
The first `/` separates the provider from the model. Model IDs can contain additional slashes.
|
|
|
|
## Configure a session
|
|
|
|
```ts
|
|
const agent = await client.agents.create({
|
|
config: {
|
|
provider: "codex/gpt-5.5",
|
|
modeId: "full-access",
|
|
thinkingOptionId: "high",
|
|
featureValues: {
|
|
web_search: false,
|
|
},
|
|
},
|
|
cwd: process.cwd(),
|
|
prompt: "Implement the accepted plan and run focused tests.",
|
|
});
|
|
```
|
|
|
|
| Field | Meaning |
|
|
| ------------------ | -------------------------------------------------------------- |
|
|
| `provider` | Required `provider/model` selection. |
|
|
| `modeId` | Provider operating or permission mode. |
|
|
| `thinkingOptionId` | Provider reasoning level. |
|
|
| `featureValues` | Values for features returned by `providers.listFeatures()`. |
|
|
| `options` | Provider-native settings such as sandbox and permission rules. |
|
|
| `systemPrompt` | Additional system or developer instructions. |
|
|
| `mcpServers` | Session-scoped MCP servers. |
|
|
| `toolPolicy` | Exact preapproval rules for MCP tools. |
|
|
|
|
[Provider options](/docs/sdk/provider-options) lists the accepted sandbox and permission settings.
|
|
|
|
## Discover installed providers and models
|
|
|
|
```ts
|
|
const snapshot = await client.providers.waitForReady({
|
|
cwd: process.cwd(),
|
|
timeoutMs: 60_000,
|
|
});
|
|
|
|
for (const entry of snapshot.entries) {
|
|
if (entry.status !== "ready") continue;
|
|
|
|
for (const model of entry.models ?? []) {
|
|
console.log(`${entry.provider}/${model.id}`);
|
|
}
|
|
}
|
|
```
|
|
|
|
An entry finishes as `ready`, `unavailable`, or `error`. `snapshot()` returns immediately and can include `loading` entries.
|
|
|
|
## Select a discovered model
|
|
|
|
```ts
|
|
const snapshot = await client.providers.waitForReady({ cwd: process.cwd() });
|
|
const entry = snapshot.entries.find((candidate) => candidate.status === "ready");
|
|
const model = entry?.models?.find((candidate) => candidate.isDefault) ?? entry?.models?.[0];
|
|
|
|
if (!entry || !model) throw new Error("No provider model is ready");
|
|
|
|
const agent = await client.agents.create({
|
|
config: {
|
|
provider: `${entry.provider}/${model.id}`,
|
|
},
|
|
cwd: process.cwd(),
|
|
prompt: "Summarize this repository.",
|
|
});
|
|
```
|
|
|
|
## Discover modes, thinking levels, and features
|
|
|
|
```ts
|
|
const models = await client.providers.listModels("codex", { cwd: process.cwd() });
|
|
const modes = await client.providers.listModes("codex", { cwd: process.cwd() });
|
|
|
|
const selectedModel = models.models[0]?.id;
|
|
const selectedMode = modes.modes[0]?.id;
|
|
if (!selectedModel) throw new Error("No Codex model is available");
|
|
|
|
const features = await client.providers.listFeatures({
|
|
provider: `codex/${selectedModel}`,
|
|
cwd: process.cwd(),
|
|
modeId: selectedMode,
|
|
});
|
|
```
|
|
|
|
Use IDs returned by the daemon. Provider installations and configured models differ between hosts.
|
|
|
|
## Diagnose an unavailable provider
|
|
|
|
```ts
|
|
const result = await client.providers.diagnostic("codex");
|
|
console.error(result.diagnostic);
|
|
```
|
|
|
|
Host-level profiles, binaries, credentials, and custom providers belong in [Custom providers](/docs/custom-providers).
|