cohere-upgrade-migration

Migrate from Cohere API v1 to v2 and upgrade SDK versions. Use when upgrading cohere-ai SDK, migrating from CohereClient to CohereClientV2, or handling breaking changes between API versions. Trigger with phrases like "upgrade cohere", "cohere migration", "cohere v1 to v2", "update cohere SDK", "cohere breaking changes".

仓库: jeremylongshore/claude-code-plugins-plus-skills
最近来源活动: 2026年7月17日 22:18
检测到的 SKILL.md 语言: 英语
星标: 2,604
分支: 378

安装方式

默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。

检查来源文件

决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。

返回搜索返回安装

Cohere Upgrade & Migration

Overview

Guide for migrating from Cohere API v1 to v2 and upgrading the cohere-ai TypeScript / cohere Python SDK. Covers every breaking change with before/after code.

Prerequisites

Current Cohere SDK installed
Git for version control
Test suite available

Instructions

Step 1: Check Current Version

# TypeScript
npm list cohere-ai

# Python
pip show cohere

# Latest versions
npm view cohere-ai version
pip index versions cohere

Step 2: Create Upgrade Branch

git checkout -b upgrade/cohere-v2-migration
npm install cohere-ai@latest
# or: pip install cohere --upgrade

Step 3: API v1 to v2 Breaking Changes

Client Import

// v1
import { CohereClient } from 'cohere-ai';
const cohere = new CohereClient({ token: '...' });

// v2
import { CohereClientV2 } from 'cohere-ai';
const cohere = new CohereClientV2({ token: '...' });

Chat Endpoint — Messages Format

// v1 — single message string
const response = await cohere.chat({
  message: 'Hello',
  preamble: 'You are helpful.',
  chatHistory: [
    { role: 'USER', message: 'Hi' },
    { role: 'CHATBOT', message: 'Hello!' },
  ],
});
console.log(response.text);

// v2 — OpenAI-compatible messages array, model required
const response = await cohere.chat({
  model: 'command-a-03-2025',  // REQUIRED in v2
  messages: [
    { role: 'system', content: 'You are helpful.' },
    { role: 'user', content: 'Hi' },
    { role: 'assistant', content: 'Hello!' },
    { role: 'user', content: 'Hello' },
  ],
});
console.log(response.message?.content?.[0]?.text);

Role Names

v1	v2
`USER`	`user`
`CHATBOT`	`assistant`
`SYSTEM`	`system`
`TOOL`	`tool`

Embed Endpoint — Required Fields

// v1 — model optional, no embedding_types
const response = await cohere.embed({
  texts: ['hello'],
});

// v2 — model, inputType, embeddingTypes all REQUIRED
const response = await cohere.embed({
  model: 'embed-v4.0',          // Required
  texts: ['hello'],
  inputType: 'search_document', // Required for v3+ models
  embeddingTypes: ['float'],    // Required for v3+ models
});

Rerank Endpoint — Model Required

// v1
const response = await cohere.rerank({
  query: 'best language',
  documents: ['Python', 'Rust'],
});

// v2
const response = await cohere.rerank({
  model: 'rerank-v3.5',  // Required
  query: 'best language',
  documents: ['Python', 'Rust'],
  topN: 2,
});

Classify Endpoint — Model Required

// v1
const response = await cohere.classify({
  inputs: ['great product'],
  examples: [/*...*/],
});

// v2
const response = await cohere.classify({
  model: 'embed-english-v3.0',  // Required
  inputs: ['great product'],
  examples: [/*...*/],
});

Streaming Changes

// v1
const stream = cohere.chatStream({ message: 'hello' });
for await (const event of stream) {
  if (event.eventType === 'text-generation') {
    process.stdout.write(event.text);
  }
}

// v2
const stream = await cohere.chatStream({
  model: 'command-a-03-2025',
  messages: [{ role: 'user', content: 'hello' }],
});
for await (const event of stream) {
  if (event.type === 'content-delta') {
    process.stdout.write(event.delta?.message?.content?.text ?? '');
  }
}

RAG / Documents

// v1 — connectors or documents as strings
const response = await cohere.chat({
  message: 'question',
  documents: [{ title: 'Doc', snippet: 'content' }],
  connectors: [{ id: 'web-search' }],
});
// citations via response.citations

// v2 — documents as data objects
const response = await cohere.chat({
  model: 'command-a-03-2025',
  messages: [{ role: 'user', content: 'question' }],
  documents: [
    { id: 'doc1', data: { text: 'content' } },
  ],
});
// citations via response.message?.citations

Tool Use

// v1 — Cohere-specific format
const tools = [{
  name: 'get_weather',
  description: 'Get weather',
  parameterDefinitions: {
    city: { type: 'str', required: true },
  },
}];

// v2 — OpenAI-compatible format
const tools = [{
  type: 'function',
  function: {
    name: 'get_weather',
    description: 'Get weather',
    parameters: {
      type: 'object',
      properties: { city: { type: 'string' } },
      required: ['city'],
    },
  },
}];

Step 4: Model Name Updates

Old Name	Current Name	Status
`command`	`command-r7b-12-2024`	Use new ID
`command-r`	`command-r-08-2024`	Use new ID
`command-r-plus`	`command-r-plus-08-2024`	Use new ID
`command-nightly`	`command-a-03-2025`	Use Command A
`embed-english-v3.0`	`embed-v4.0`	Upgrade recommended
`rerank-english-v3.0`	`rerank-v3.5`	Upgrade recommended

Step 5: Python Migration

# v1
import cohere
co = cohere.Client(api_key="...")
response = co.chat(message="hello")
print(response.text)

# v2
import cohere
co = cohere.ClientV2()  # reads CO_API_KEY
response = co.chat(
    model="command-a-03-2025",
    messages=[{"role": "user", "content": "hello"}],
)
print(response.message.content[0].text)

Step 6: Run Tests and Verify

npm test
# Fix any type errors from changed response shapes
# Key changes: response.text → response.message?.content?.[0]?.text
#              response.citations → response.message?.citations

git add -A
git commit -m "chore: migrate to Cohere API v2"

Migration Codemod (Find & Replace)

# Find all v1 imports
grep -rn "CohereClient\b" src/ --include="*.ts" | grep -v "CohereClientV2"

# Find v1 chat calls
grep -rn "\.chat({" src/ --include="*.ts" -A2 | grep "message:"

# Find v1 response access
grep -rn "response\.text\b" src/ --include="*.ts"

# Find v1 streaming events
grep -rn "eventType.*text-generation" src/ --include="*.ts"

Output

Updated SDK to latest version
Migrated all endpoints from v1 to v2 format
Updated model IDs to current names
All tests passing against v2 API

Error Handling

Error After Migration	Cause	Fix
`model is required`	Missed adding model param	Add model to every call
`response.text is undefined`	v1 response shape	Use `response.message?.content?.[0]?.text`
`embedding_types required`	v2 embed requirement	Add `embeddingTypes: ['float']`
`input_type required`	v2 embed requirement	Add `inputType: 'search_document'`

Resources

Next Steps

For CI integration during upgrades, see cohere-ci-integration.