Anthropic SDK 2.0 migrace: co ti rozbije kód (návod)

Anthropic SDK 2.0 migrace je úkol, který tě tento týden potká, pokud máš v projektu Claude API. 21. října 2026 vyšla nová verze API 2026-10-21 a spolu s ní nové major verze klientských SDK. Nové SDK posílá novou verzi API automaticky, takže stačí pip install -U anthropic a část kódu najednou vrací chybu 400 nebo se chová jinak. Tenhle návod ti ukáže, co se přesně mění, jak to najdeš ve svém kódu a v jakém pořadí to opravit, aby ti nespadla produkce.

Nejde o nový model, ale o údržbu integrace. Právě proto se vyplatí udělat ji v klidu a dřív, než ti ji vynutí první chyba v logu.

01Co přesně vyšlo a koho se to týká

Podle release notes Claude Platform z 21. 10. 2026 vyšly tyto verze, které už posílají API verzi 2026-10-21:

• Python SDK 2.0.0
• TypeScript SDK 1.0.0
• C# SDK 13.0.0
• Go SDK 2.0.0
• Java SDK 3.0.0
• PHP SDK 1.0.0
• Ruby SDK 2.0.0
• CLI ant 2.0.0

Nové SDK a CLI jsou navíc pod licencí Apache 2.0 místo MIT. Pokud máš ve firmě schvalování licencí, nezapomeň to nahlásit.

Pro koho Týká se tě to, pokud voláš Claude API přes SDK nebo přímo přes HTTP a posíláš hlavičku anthropic-version. Pokud používáš jen aplikaci Claude nebo Claude Code, nemusíš dělat nic.

Pozor Pokud voláš API bez SDK, nic se ti samo nezmění. Dokud neposíláš anthropic-version: 2026-10-21, běží tvůj kód na staré verzi. Migraci tak můžeš naplánovat, ale nový SDK ji udělá za tebe hned po upgradu.

02Jak na migraci SDK: tři kroky v pořadí

Oficiální migrační návod (21. 10. 2026) doporučuje jednoduchý postup. Já ho jen převádím do praxe.

03Messages API: tři změny, které vrací chybu 400

Tyto změny platí pro POST /v1/messages, počítání tokenů i každý požadavek v dávce (Message Batch) vytvořené s novou verzí.

Parametry temperature, top_p a top_k zmizely

Tohle je pravděpodobně nejčastější zásah. Požadavek, který pošle temperature, top_p nebo top_k, vrací chybu 400, a to i když jde o výchozí hodnotu. Nové SDK a CLI tyto parametry už vůbec nemají.

Oprava je jednoduchá: parametry smaž. Požadavek se pak vzorkuje s výchozími hodnotami, včetně temperature 1,0, stejně jako požadavek bez nich na staré verzi.

Pozor na dopad. U modelů, které už přijímají jen výchozí hodnoty (Claude 4.7 a novější), se nic nemění. U modelů, které jiné hodnoty přijímaly (třeba Claude Sonnet 4.6), ztratíš efekt snížené teploty pro stabilnější výstup. Nic jiného ho nenahrazuje. Pokud na nižší teplotě opravdu stavíš, buď parametr přestaneš posílat, nebo necháš ten konkrétní požadavek na verzi 2023-06-01.

Pokud ladíš, kolik má model přemýšlet, nezapomeň na reasoning effort. To je jiný ovladač než teplota.

Dokumenty v odpovědích asistenta

Blok typu document umístěný přímo ve zprávě asistenta teď vrací chybu 400. Dokumenty posílej ve zprávách uživatele. Dokument vnořený v jiném bloku, například ve výsledku nástroje web fetch, který vrátil Claude, se dál přijímá.

Citace ve zprávách uživatele

Textový blok s neprázdným polem citations ve zprávě uživatele (včetně bloků search_result) vrací chybu 400. Citace z takových bloků odstraň. Citace v textových blocích asistenta, tedy dřívější odpovědi Claude, které posíláš zpět, dál fungují. Stejně tak nastavení "citations": {"enabled": true} u dokumentů a výsledků vyhledávání.

04Admin API a Enterprise Analytics: přejmenovaná pole

Čteš-li data z Admin API nebo z Claude Enterprise Analytics API (třeba pro vlastní reporting nákladů), odpovědi už neobsahují stará jména polí. Pár příkladů z návodu:

• RBAC skupiny: roles je nově role_ids.
• Členové RBAC skupin: group_id je nově rbac_group_id.
• RBAC role: name je nově display_name.
• Rate limity: group_type je nově group.type.
• Analytics: actor.email je nově actor.email_address a summaries je nově data.

Nejzajímavější je workspace_id u API klíčů. Pole zmizelo a místo něj čteš scope. U klíče vázaného na workspace (včetně výchozího) je scope.workspace_id skutečné ID workspace. Klíč platný pro všechny workspace má scope s hodnotou {"type": "organization"} a bez workspace_id.

Tip Pokud tvůj kód bral null jako výchozí workspace, porovnávej teď scope.workspace_id s ID výchozího workspace. To zjistíš voláním List Workspaces s include_default=true, hledáš workspace s názvem „Default".

05Změny v SDK a CLI nezávislé na verzi API

Nové major verze mají vlastní breaking changes. Nejdůležitější z nich:

Typ MessageParam je nově sjednocení tří typů

MessageParam byl dřív jeden typ pro všechny role. Nově existují UserMessageParam, AssistantMessageParam a SystemMessageParam (a stejně pro BetaMessageParam). Zprávy zapsané jako slovník, například {"role": "user", "content": "Hello"}, se měnit nemusí. Ale volání MessageParam(...) jako konstruktoru nově končí chybou TypeError. Zapiš zprávu jako slovník s anotací typu.

Pokud máš funkci, která skládá zprávu s proměnnou role, typová kontrola si začne stěžovat. Řešení je větvení: pro roli user vrať jeden slovník, pro assistant druhý.

Klientská komprese v tool runneru zmizela

Týká se SDK pro TypeScript a Ruby. Volba compactionControl je pryč a nahradila ji komprese na straně serveru, která shrnuje konverzaci uvnitř API. V TypeScriptu nově zapneš kompresi přes betas: ["compact-2026-01-12"] a context_management s prahem v tokenech. Minimální práh je 50 000 tokenů.

Pokud stavíš dlouhé běhy agentů, podívej se také na to, jak dlouhé běhy agenta v Claude Code headless.

Text Completions je pryč

Staré Text Completions API zmizelo z SDK pro TypeScript, Go, Java a Ruby i z CLI. Příkaz ant completions create už neexistuje, použij ant messages create. Text odpovědi se přesunul z pole completion do content.0.text. Skript, který používal --transform completion, přepni na --transform content.0.text.

Models metody už nepřijímají betas

Nebetové metody pro modely už nemají parametr betas. Potřebuješ-li poslat hlavičky pro beta funkce, volej stejné metody na client.beta.models. V Pythonu to znamená změnu z client.models.list(betas=[...]) na client.beta.models.list(betas=[...]).

API klíč se posílá jako Authorization: Bearer

Tohle je změna, kterou snadno přehlédneš a pak hodinu hledáš, proč ti přestal fungovat firemní gateway. SDK a CLI teď posílají klíč v hlavičce Authorization: Bearer <klíč> místo X-Api-Key. API přijímá obě varianty, takže pokud mluvíš přímo s API, nemusíš nic měnit. Změna ale zasáhne proxy nebo gateway, která čte či nastavuje X-Api-Key.

Máš-li před Claude API vlastní proxy, třeba kvůli logování nebo skrývání API klíčů před agenty, uprav ji tak, aby četla Authorization. Případně vrať klíč do X-Api-Key pomocí funkce auth na HTTP klientovi. Ta se spustí u každého požadavku včetně opakovaných pokusů.

06Checklist migrace: jak najít problémy dřív než produkce

Tohle je postup, který bych na tvém místě použil. Je odvozený z migračního návodu, ne z mého vlastního testu na tvém kódu, takže ber jako výchozí bod.

1. Najdi sampling parametry. Vyhledej v repozitáři temperature, top_p a top_k. Každý výskyt v Messages požadavku musí pryč.
2. Najdi citace a dokumenty. Hledej citations ve zprávách uživatele a bloky document ve zprávách asistenta.
3. Najdi gateway. Zkontroluj proxy, WAF a logovací vrstvy, které čtou X-Api-Key.
4. Najdi Admin API. Projdi skripty pro reporting nákladů a práv. Hledej workspace_id, group_type a actor.email.
5. Najdi zastaralé věci. Vyhledej Text Completions, compactionControl a betas u Models.
6. Spusť typovou kontrolu. U Pythonu mypy nebo pyright ti ukážou většinu problémů s MessageParam.
7. Otestuj na stagingu. Pošli pár reálných požadavků včetně dávky a zkontroluj, že se neobjevila chyba 400.

Tip Pokud máš při migraci co ztratit, nasaď změnu nejdřív na jedno méně kritické volání. Pro rozdělení provozu podle modelu a ceny se hodí model routing. Po nasazení zapni monitoring agentů v produkci, aby ti případné chyby 400 hned neunikly.

07Kdy migraci SDK odložit

Není nutné spěchat ve všech případech. Zvaž odklad, pokud:

• voláš Claude přes Bedrock se starším modelem než Claude 4.7,
• na nižší teplotě stavíš kvalitu výstupu a nemáš jak ji nahradit,
• máš gateway, kterou nemůžeš rychle upravit.

V takových případech zůstaň na dosavadní verzi SDK nebo posílej anthropic-version: 2023-06-01 u konkrétních volání. Pro nové projekty ale rovnou začni na verzi 2026-10-21. Dřív nebo později tě k tomu stejně dotlačí nové modely, jako to bylo při přechodu na Claude Opus 5.5 nebo Fable 5.1.

Stejnou logiku, tedy malý pokus, ověření a pak teprve plošné nasazení, najdeš i v článku o tom, jak vyladit AI harness bez výměny modelu.

08Časté otázky

09Shrnutí

Anthropic SDK 2.0 migrace se vejde do jednoho odpoledne, když víš, kde hledat: sampling parametry, citace a dokumenty, hlavičku X-Api-Key v gateway a přejmenovaná pole v Admin API. Nejdřív najdi problémová místa, pak uprav kód, nasaď upgrade a opravy společně a otestuj na stagingu. Na Bedrock se starším modelem zůstaň u staré verze, dokud nepřejdeš na Claude 4.7 nebo novější.

Zdroje: Migrating to API version 2026-10-21 (Anthropic, 21. 10. 2026) a Claude Platform release notes (21. 10. 2026).