For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://modelgates.ai/docs/_mcp/server.

Migrating to @modelgates/agent

Using an AI coding assistant? Install the migration skill to let your agent handle the import updates for you: gh skill install ModelGatesTeam/skills modelgates-agent-migration

The agent toolkit (callModel, tool, stop conditions, etc.) has moved from @modelgates/sdk to a standalone @modelgates/agent package. The agent package includes its own ModelGates client class, so you no longer need @modelgates/sdk as a dependency for agent workflows.

Who needs to migrate?

You need to migrate if your code imports any of the following from @modelgates/sdk:

• callModel / ModelResult
• tool / Tool / tool type guards
• Stop conditions (stepCountIs, hasToolCall, etc.)
• Async parameters (CallModelInput, resolveAsyncFunctions)
• Conversation state helpers
• Message format converters (fromClaudeMessages, fromChatMessages, etc.)

If you only use the REST API client for non-agent features (client.chat.send(...), client.models.list(), etc.), no changes are needed.

Step 1: Install the new package

npm install @modelgates/agent

pnpm add @modelgates/agent

yarn add @modelgates/agent

bun add @modelgates/agent

Step 2: Update imports

Replace @modelgates/sdk subpath imports with the equivalent @modelgates/agent subpath.

Client class

@modelgates/agent ships its own ModelGates client, so you can drop the @modelgates/sdk dependency entirely if you only use agent features:

- import ModelGates from '@modelgates/sdk';- import { callModel } from '@modelgates/sdk/funcs/call-model';+ import { ModelGates } from '@modelgates/agent';   const client = new ModelGates({    apiKey: process.env.MODELGATES_API_KEY,  });++ const result = client.callModel({+   model: 'openai/gpt-4o',+   input: 'Hello',+ });+ const text = await result.getText();

You can also import the client from a direct subpath:

import { ModelGates } from '@modelgates/agent/client';

Core imports

- import { callModel } from '@modelgates/sdk/funcs/call-model';+ import { callModel } from '@modelgates/agent/call-model'; - import { ModelResult } from '@modelgates/sdk/lib/model-result';+ import { ModelResult } from '@modelgates/agent/model-result'; - import { tool } from '@modelgates/sdk/lib/tool';+ import { tool } from '@modelgates/agent/tool';

Tool types and guards

- import type { Tool } from '@modelgates/sdk/lib/tool-types';+ import type { Tool } from '@modelgates/agent/tool-types'; - import {-   hasExecuteFunction,-   isGeneratorTool,- } from '@modelgates/sdk/lib/tool-types';+ import {+   hasExecuteFunction,+   isGeneratorTool,+ } from '@modelgates/agent/tool-types';

Stop conditions

- import {-   stepCountIs,-   hasToolCall,-   maxCost,- } from '@modelgates/sdk/lib/stop-conditions';+ import {+   stepCountIs,+   hasToolCall,+   maxCost,+ } from '@modelgates/agent/stop-conditions';

Async parameters

- import type {-   CallModelInput,- } from '@modelgates/sdk/lib/async-params';+ import type {+   CallModelInput,+ } from '@modelgates/agent/async-params';

Conversation state and message formats

Conversation helpers and message format converters are available from the package barrel:

- import {-   createInitialState,-   updateState,-   fromClaudeMessages,-   fromChatMessages,- } from '@modelgates/sdk';+ import {+   createInitialState,+   updateState,+   fromClaudeMessages,+   fromChatMessages,+ } from '@modelgates/agent';

Step 3: Verify your build

Run your type checker and tests to confirm everything resolves correctly:

npx tsc --noEmitnpm test

Full import mapping reference

Automated migration

The script below handles subpath imports automatically. Barrel imports (from '@modelgates/sdk') and client class imports (import ModelGates from '@modelgates/sdk') must be updated manually — a blanket replacement on the bare package name would also match subpath imports and break your code. See the Client class and Conversation state sections above for the correct replacements.

# Using sed (macOS)find src -name '*.ts' -o -name '*.tsx' | xargs sed -i '' \  -e "s|@modelgates/sdk/funcs/call-model|@modelgates/agent/call-model|g" \  -e "s|@modelgates/sdk/lib/model-result|@modelgates/agent/model-result|g" \  -e "s|@modelgates/sdk/lib/tool-types|@modelgates/agent/tool-types|g" \  -e "s|@modelgates/sdk/lib/tool|@modelgates/agent/tool|g" \  -e "s|@modelgates/sdk/lib/stop-conditions|@modelgates/agent/stop-conditions|g" \  -e "s|@modelgates/sdk/lib/async-params|@modelgates/agent/async-params|g"

# Using sed (Linux)find src -name '*.ts' -o -name '*.tsx' | xargs sed -i \  -e "s|@modelgates/sdk/funcs/call-model|@modelgates/agent/call-model|g" \  -e "s|@modelgates/sdk/lib/model-result|@modelgates/agent/model-result|g" \  -e "s|@modelgates/sdk/lib/tool-types|@modelgates/agent/tool-types|g" \  -e "s|@modelgates/sdk/lib/tool|@modelgates/agent/tool|g" \  -e "s|@modelgates/sdk/lib/stop-conditions|@modelgates/agent/stop-conditions|g" \  -e "s|@modelgates/sdk/lib/async-params|@modelgates/agent/async-params|g"

The tool-types replacement runs before tool to avoid partial matches. After running the script, search your codebase for any remaining from '@modelgates/sdk' (without a / subpath) to find barrel and client imports that need manual updates.

FAQ

Do I still need @modelgates/sdk?

Only if you use non-agent REST API features like client.models.list(), client.credits.get(), or client.chat.send(). If your code only uses callModel, tools, and the agent client, you can remove @modelgates/sdk entirely.

Can I use both packages together?

Yes. They are designed to work side by side. Use @modelgates/sdk for REST API features and @modelgates/agent for the agent toolkit:

import ModelGates from '@modelgates/sdk';import { callModel } from '@modelgates/agent/call-model';import { tool } from '@modelgates/agent/tool';

Will the old imports keep working?

The agent exports will be removed from @modelgates/sdk in a future major version. Update your imports now to avoid a breaking change later.

Do I need to change my API key or configuration?

No. @modelgates/agent uses the same API key and endpoints. No server-side changes are required.