Volání nástrojů agentem: proč váš agent vybírá špatný nástroj

Volání nástrojů agentem: proč váš agent vybírá špatný nástroj

Osvědčené postupy volání nástrojů agentem jsou tím, co stojí mezi funkčním demem a agentem, který v produkci tiše volá špatný nástroj. Inženýrský tým Anthropic změřil, že jediný přepsaný popis zkrátil jeden výsledek nástroje z 206 tokenů na 72, a Claude Code nyní natvrdo omezuje každou odpověď nástroje na 25 000 tokenů, protože únik je reálný. Váš agent selhává čtyřmi způsoby: špatný nástroj, špatné argumenty, nekontrolované smyčky a únik tokenů. A každý z nich má opravu, kterou můžete nasadit ještě tento týden.

Klíčové body:

• Volání nástrojů agentem selhává přesně čtyřmi způsoby: špatný nástroj, špatné argumenty, nekontrolované smyčky a únik tokenů.
• Popisy nástrojů jsou jedinou instrukcí, kterou model vidí v okamžiku výběru, takže opravují většinu volání špatného nástroje.
• Plochá schémata tvarovaná podle úlohy s validovanými vstupy eliminují většinu selhání se špatnými argumenty.
• Stručné odpovědi nástrojů a evaluační smyčka při každé změně udržují náklady na tokeny a regrese měřitelné.

Proč volání nástrojů agentem selhává v produkci?

Volání nástrojů agentem selhává čtyřmi způsoby: model vybere špatný nástroj, napíše špatné argumenty, točí se v nekontrolované smyčce nebo plýtvá tokeny přes objemné odpovědi. Každé selhání zasahuje jiný krok smyčky volání, takže na pořadí oprav záleží. Začněte výběrem, protože špatná volba nástroje otráví každý následující krok.

Kompletní předpis na první pohled:

Procházejte je v tomto pořadí. Postupy 1 a 2 zaberou jedno odpoledne a odstraní většinu selhání se špatným nástrojem a špatnými argumenty, které dnes vidíte. Popis nástroje není dokumentace. Je to jediná instrukce, kterou model dostane v okamžiku výběru.

Fáze 1: Navrhněte nástroje, které model skutečně dokáže používat

Nejlevnější zisky spolehlivosti při volání nástrojů agentem leží ve vašich definicích nástrojů, nikoli v promptech nebo volbě modelu. Model nikdy nečte vaši API dokumentaci ani README. Vidí název, řetězec popisu a JSON schéma a rozhoduje se výhradně podle nich. Když tyto tři věci zvládnete, přesnost výběru se posune dřív, než se dotknete čehokoli dalšího.

Postup 1: Pište popisy, podle kterých model dokáže jednat

Pište popisy nástrojů jako instrukce pro model, ne jako API dokumentaci. Popis, který uspokojí lidského vývojáře („REST wrapper pro endpoint users"), nedává modelu žádný základ pro rozhodnutí. Inženýrský průvodce Anthropic pro psaní nástrojů i jejich osvědčené postupy pro definice nástrojů prosazují stejný vzor: řekněte, kdy nástroj použít, co vrací a kdy ho NEpoužívat.

{
  "name": "get_user",
  "description": "Fetches a user profile. Use ONLY when you already have a user_id. Do NOT use to search or list users; call search_users instead. Returns name, email, plan. Errors if user_id is not a valid UUID."
}

oproti verzi, kterou většina týmů nasazuje:

{
  "name": "get_user",
  "description": "Gets a user."
}

Dvě pravidla zde odvedou většinu práce. Zaprvé, pojmenujte parametry tak, aby jejich význam byl jednoznačný: user_id, nikdy user nebo id, protože user svádí model k předání jména nebo e-mailu tam, kam patří UUID. Zadruhé, explicitně uveďte vyloučení. „NEpoužívejte k hledání uživatelů" zabrání většímu počtu volání špatného nástroje než jakékoli množství pozitivního popisu, protože modely zaměňují překrývající se nástroje mnohem častěji, než špatně rozumí jednotlivým, jasně ohraničeným. Pro mechaniku na úrovni poskytovatele, jak se tyto definice dostávají k API OpenAI, Anthropic a Google, viz náš průvodce function calling pro více poskytovatelů.

Postup 2: Udržujte schémata plochá a tvarovaná podle úlohy

Udržujte vstupní schémata plochá, s každým polem, které úloha skutečně potřebuje, a žádným, které nepotřebuje. Vnořené objekty s volitelnými větvemi jsou místem, kde se množí selhání se špatnými argumenty: model musí odvodit strukturu, jejíž příklady nikdy nevidí. Průvodce function calling od OpenAI přijímá libovolné JSON Schema, ale permisivní není totéž jako spolehlivé.

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "ticket": {
        "type": "object",
        "properties": {
          "details": {
            "type": "object",
            "properties": {
              "title": { "type": "string" },
              "meta": { "type": "object" }
            }
          }
        }
      }
    }
  }
}

Zplošťte to na úlohu:

{
  "name": "create_ticket",
  "parameters": {
    "type": "object",
    "properties": {
      "title": { "type": "string" },
      "priority": { "type": "string", "enum": ["low", "medium", "high"] },
      "assignee_id": { "type": "string" }
    },
    "required": ["title", "priority"]
  }
}

Enumerace porazí volný text u každého pole s omezenou množinou hodnot. Pole required porazí volitelné vše. Pokud model téměř vždy potřebuje určité pole, udělejte ho ve schématu nástroje povinné, i když ho vaše API označuje jako volitelné. Nezrcadlíte své API. Navrhujete rozhraní, které jeden konkrétní model dokáže správně vyplnit.

Fáze 2: Spravujte sadu nástrojů, ne jen jednotlivé nástroje

Kvalita jednotlivých nástrojů přestává stačit ve chvíli, kdy agent nese více než hrst nástrojů, protože chyby výběru rostou s velikostí seznamu, který model čte.

Postup 3: Balte vícekrokové API sekvence do atomických nástrojů

Sbalte každou pevnou sekvenci API volání do jednoho atomického nástroje. Inženýrský článek Anthropic používá jako vzor schedule_event a get_customer_context: jedno volání, které udělá celou práci, porazí tři volání, která agent musí pokaždé správně zřetězit. Každý článek řetězce je další kolo, kde model může uváznout, špatně zopakovat nebo se zacyklit.

# Co agent dělá BEZ atomického nástroje: 3 volání, 3 příležitosti k selhání
calendar = call_tool("list_calendars", {})
free = call_tool("find_free_slot", {"calendar_id": calendar["items"][0]["id"], "duration": 30})
call_tool("create_event", {"calendar_id": calendar["items"][0]["id"], "start": free["start"]})

# Jeden atomický nástroj: sekvence žije ve vašem kódu, ne v hlavě modelu
call_tool("schedule_event", {"duration": 30, "attendees": ["[email protected]"]})

Pravidlo palce: pokud model musí vždy zavolat B po A, jsou A a B jeden nástroj ve dvou kostýmech.

Postup 4: Jmenné prostory, prořezávání a dynamické filtrování nástrojů

Dejte každému nástroji jmenný prostor a každému agentovi ukazujte pouze podmnožinu, kterou jeho aktuální úloha potřebuje. Obecné názvy kolidují v okamžiku, kdy připojíte dvě integrace. Představte si agenta napojeného na dva MCP servery, které oba vystavují nástroj nazvaný search: dvě identická slovesa, žádný způsob, jak je rozlišit. Anthropic dokumentuje měřitelné zisky v evaluacích díky prefixovým jmenným prostorům:

Prořezávání je stejně důležité jako pojmenování. Agent podpory nepotřebuje mít načtené fakturační nástroje, když odpovídá na dotaz o heslu. Vzorz plánovač-pracovník, kde plánovač směruje úlohu pracovníkovi, který načte pouze relevantní nástroje, je standardní řešení; návod LangGraph na dynamické načítání nástrojů popisuje implementaci. Kolik nástrojů je příliš mnoho? Berte 5–10 na agenta jako pracovní rozmezí, ne zákon: přesnost klesá s rostoucím seznamem a lékem je filtrování, ne větší model. Pokud vybíráte samotnou vrstvu směrování a filtrování, porovnejte možnosti v našem přehledu nejlepších knihoven pro function calling.

Fáze 3: Kontrolujte, co se vrací i co odchází

Smyčka běží oběma směry a většina týmů inženýrsky řeší jen odchozí polovinu. To, co vaše nástroje vracejí, určuje, kolik kontextového okna přežije do dalšího kola, a to, co vaše validace odmítne, určuje, zda se model poučí ze svých chyb, nebo je opakuje.

Postup 5: Vracejte stručné výsledky s vysokou informační hodnotou

Vraťte nejmenší výsledek, podle kterého model dokáže jednat, s lidsky čitelnými identifikátory místo surových ID. Inženýrský článek Anthropic dokumentuje nástroj, jehož výchozí výsledek měl 206 tokenů; stručné nastavení response_format zkrátilo stejný výsledek na 72 tokenů, zhruba na třetinu. Vynásobte to desítkami volání na úlohu a rozhoduje to o tom, zda váš agent vůbec dokončí práci.

// Před: 206 tokenů (tvar podle dokumentovaného příkladu Anthropic)
{
  "status": "success",
  "data": {
    "id": "8f14e45f-ceea-3f9c-a2f3-90c1b5e0a7d2",
    "object": "task", "created_at": "2026-07-02T09:14:00Z",
    "updated_at": "2026-07-11T16:40:12Z", "completed_at": null,
    "assignee": {"id": "c9a1...f2", "object": "user"},
    "projects": [{"id": "b7d3...91", "object": "project"}],
    "permalink": "https://app.asana.com/0/.../f"
  }
}

// Po: 72 tokenů
{ "task": "Fix login redirect", "assignee": "Dana Kim", "project": "Web App", "due": "2026-07-20" }

Dva další detaily ze stejného zdroje: Anthropic podporuje enumeraci response_format (detailed versus concise) v definicích nástrojů, takže můžete deklarovat požadovaný tvar místo parsování celého proudu. A Claude Code omezuje odpovědi nástrojů na 25 000 tokenů, tvrdý strop, který objemné výsledky stejně zkrátí. Anthropic také uvádí jako svůj poznatek, že překlad UUID na sémantické názvy měřitelně snížil halucinace při vyhledávání, proto výše uvedený payload „po" říká „Dana Kim" a ne c9a1...f2. Objemné odpovědi jsou i nákladový problém; viz náš průvodce snížením nákladů na LLM API pro kompletní obrázek.

Postup 6: Validujte každé volání a nechte chyby učit model

Validujte každé volání nástroje na straně serveru a vracejte chyby, které obsahují opravu. Článek Martina Fowlera o function calling to formuluje přímočaře: nikdy nedůvěřujte výstupu modelu. Předá řetězce tam, kam patří enumerace, a vymyslí ID, která neexistují.

def create_ticket(args):
    if args.get("priority") not in {"low", "medium", "high"}:
        return {"error": f"priority must be one of: low, medium, high. Got '{args.get('priority')}'. Pass priority='medium' for normal issues."}
    if not is_valid_uuid(args.get("assignee_id")):
        return {"error": "assignee_id must be a UUID. Call list_team_members to get valid IDs, then retry."}
    return db.create_ticket(**args)

Chybový řetězec je celá hra. Porovnejte:

# Nepomocné: model zopakuje stejné špatné volání
{"error": "invalid input"}

# Pomocné: model přesně ví, co změnit
{"error": "priority must be one of: low, medium, high. Got 'urgent'. Use 'high'."}

Každá validační chyba, kterou váš nástroj vrátí, je prompt, který píšete pro další pokus modelu. Chyby, které pojmenují omezení a ukážou na opravný nástroj, změní smyčku opakování na jednorázové zotavení. Toto je také vaše první bezpečnostní linie obrany; náš průvodce LLM guardrails to pokrývá do hloubky.

Fáze 4: Jak to uděláte bezpečné a pak měřitelné?

Bezpečnost a měřitelnost jsou stejná fáze, protože nechráněná destruktivní akce i neměřená regrese se projeví jako incidenty, které jste neviděli přicházet. Chraňte akce, které nelze vrátit, pak instrumentujte vše, aby další změna nástroje byla rozhodnutí s důkazy, ne naděje.

Postup 7: Destruktivní akce podmiňte potvrzením člověka

Oddělte nástroje pro čtení od nástrojů pro zápis a na cokoli destruktivního dejte bránu s potvrzením člověka. Anotace nástrojů ve specifikaci MCP existují přesně pro toto: destructiveHint označuje nástroje, které provádějí destruktivní aktualizace, a openWorldHint označuje nástroje, které se dotýkají externích systémů, takže klienti mohou před spuštěním vyžádat potvrzení. Používejte je.

Režim selhání není hypotetický. Laurent Kubaski zdokumentoval případ ve svém článku o volání nástrojů z července 2025 s odkazem na původní hlášení, kde uživatel požádal Copilot v Excelu, aby pracoval s řádkem 4, a agent místo toho pracoval s řádkem 8. Žádná brána potvrzení nestála mezi špatným řádkem a zápisem. Řešením je vzor, který AWS dokumentuje pro Bedrock Agents: agent připraví akci, vrátí ji ke schválení a provede ji teprve po potvrzení člověkem. Cursor dělá totéž pro úpravy souborů. Omezte oprávnění na čtení tam, kde čtení je vše, co úloha potřebuje, a berte brány potvrzení jako součást vaší injekční plochy, téma našeho průvodce prevencí prompt injection.

Postup 8: Spouštějte evaluační smyčku při každé změně nástroje

Spusťte malou evaluační sadu před a po každé změně nástroje a čtěte metriky v pevném pořadí. Optimalizační průvodce Paragon navrhuje čtyřmetrický rámec, který stojí za převzetí:

Evaluační kuchařka Anthropic, postavená na reálných MCP evaluacích Slack a Asana, ukazuje, jak vypadají dobré a špatné evaluační úlohy:

# Slabé: vágní, mnoho platných cest, nemožné skórovat
"Use the Asana tools to organize some work."

# Silné: jeden správný nástroj, ověřitelné argumenty, binární výsledek
"Create a task titled 'Renew TLS cert' in project 'Infra' assigned to [email protected], due 2026-08-15. Expect exactly one create_task call with those four fields."

Naše interpretace, označená jako taková: publikovaná čísla vám dávají pořadí, ve kterém pracovat. Kontrolujte správnost nástroje jako první, protože vlastní měření Anthropic ukazují, že změny popisu a pojmenování ji posouvají přímo (přepis z 206 na 72 tokenů, poznatek o halucinacích UUID-na-název), a nechte efektivitu úlohy na konec, protože většinou odráží selhání, která první tři metriky už zachytily. Pro startovací sadu navrhněte 15–30 úloh, dvě až tři na nástroj, každou s jedním očekávaným voláním a binární podmínkou průchodu. Tato velikost stačí k zachycení regrese z přepsání popisu bez týdne značkování a čteme nastavení Slack a Asana v kuchařce jako důkaz, že takto malá sada je zamýšlený výchozí bod, ne zkratka. Hlubší mechanika je v našem průvodci evaluací AI agentů v produkci a pokud vaše evaluační výsledky říkají, že nástroje samotné jsou v pořádku, ale orchestrace ne, pak je čas přehodnotit volbu frameworku vůči nejlepším AI agent frameworkům.

Volání nástrojů agentem vs MCP: jaký je rozdíl?

MCP je standard transportu a registru, ne vrstva spolehlivosti, takže stejných osm postupů platí, ať vaše nástroje přicházejí přes MCP, nebo jsou definovány inline. Nativní volání nástrojů je smlouva mezi modelem a poskytovatelem: jak model emituje tool_call a čte tool_result. MCP standardizuje, jak se nástroje dostávají k modelu; nedělá nic pro to, zda model vybere správný.

MCP server, který vystavuje nástroj nazvaný search s popisem „searches things", selže identicky jako inline funkce definovaná stejným způsobem. Opravte definici, pak se starajte o transport. Náš průvodce Model Context Protocol pokrývá protokolovou stranu od začátku do konce.

Jak Techsy aplikuje těchto osm postupů

Při každém klientském buildu agenta vynucujeme tři z nich před nasazením čehokoli jiného: popisy psané jako instrukce (Postup 1), validační brány na každém zapisovacím nástroji (Postup 6) a evaluační sada, která běží před deployem, ne po incidentu (Postup 8). Tyto tři pokrývají volání špatného nástroje, volání se špatnými argumenty a regrese, které obojí znovu zavádějí, což je místo, kde začal každý produkční incident agenta, který jsme kdy debugovali. Zbývajících pět postupů následuje, jak agent roste. Pokud je váš agent za fází dema a vybírá špatné nástroje, získejte bezplatnou konzultaci a řekneme vám, který z osmi opravit jako první.

O autorovi

Mert Batur je spoluzakladatel Techsy.io, kde tým nasazuje AI agenty, automatizační systémy a hlasové/SDR pipeline pro B2B klienty. Píše o stacku LLM nástrojů, který tým Techsy skutečně používá v produkci. Spojte se na LinkedIn.

Často kladené dotazy

Co je volání nástrojů agentem?

Volání nástrojů agentem je mechanismus, při kterém se LLM rozhodne vyvolat externí funkci, emituje strukturovaný tool_call a čeká, až váš kód vrátí tool_result, nad kterým může uvažovat. Je to to, co mění chatovací model v agenta, který dokáže dotazovat databáze, volat API a provádět akce: model vybírá nástroj a argumenty, váš exekutor je spouští.

Jak funguje smyčka volání nástrojů agentem?

Smyčka má pět kroků: požadavek uživatele dorazí k modelu, model vybere nástroj a napíše tool_call, váš exekutor ho spustí, tool_result se vrátí modelu a model buď odpoví, nebo vydá další volání. Tento cyklus se opakuje, dokud úloha není hotova. Čtyři režimy selhání v tomto průvodci se každý nacházejí na konkrétním kroku této smyčky.

Proč můj agent vybírá špatný nástroj?

Obvykle proto, že se dva nástroje překrývají a jejich popisy neříkají, který je který. Model vybírá pouze podle názvů a popisů, takže „gets a user" versus „finds users" vypadá jako zaměnitelné. Opravte to vylučovacími řádky („NEpoužívejte k hledání"), názvy ve jmenných prostorech a menším počtem nástrojů v kontextu. Test Kubaski se čtyřmi modely ukázal, že i silné modely špatně směrují na nejednoznačných seznamech.

Jak přinutím agenta pro volání nástrojů, aby strukturoval svůj výstup?

Omezte schéma, ne prompt. Použijte enumerace pro omezená pole, pole required pro vše, co úloha potřebuje, a ploché objekty místo vnořených. Pro finální odpověď místo volání nástroje vynutí konkrétní tvar funkce poskytovatele, jako jsou strukturované výstupy OpenAI a režimy tool-choice Anthropic. Náš průvodce strukturovanými výstupy pokrývá obě cesty s kódem.

Volání nástrojů agentem vs MCP: jaký je rozdíl?

Nativní volání nástrojů je smlouva mezi vaším kódem a jedním poskytovatelem modelu: formát zpráv tool_call a tool_result. MCP je protokolová vrstva, která standardizuje, jak jsou nástroje objevovány a doručovány jakémukoli kompatibilnímu klientovi. MCP mění potrubí, ne spolehlivost. Špatně popsaný nástroj selže stejným způsobem po obou cestách, jak vysvětluje náš průvodce Model Context Protocol.

Kolik nástrojů je příliš mnoho pro LLM agenta?

Berte 5–10 nástrojů na agenta jako pracovní rozmezí, ne zákon. Přesnost výběru klesá s rostoucím viditelným seznamem, zejména když se názvy nebo popisy překrývají. Řešením není větší model, ale filtrování: načtěte pouze podmnožinu, kterou aktuální úloha potřebuje, pomocí rozdělení plánovač-pracovník. Dejte všemu jmenný prostor, aby dvě integrace nikdy nevystavovaly holý search.

Jaký je nejlepší model pro volání nástrojů?

Neexistuje jediná odpověď a publikované benchmarky v tomto prostoru rychle stárnou. Špičkové modely od OpenAI, Anthropic a Google všechny zvládnou základní úlohy s nástroji, zatímco menší modely spárované s dobře navrženými nástroji často dokončí úlohy téměř stejně často za zlomek nákladů na tokeny. Postavte evaluační sadu s 15–30 úlohami z Postupu 8 a testujte kandidáty proti vlastním nástrojům.

Jak snížím náklady na tokeny z volání nástrojů?

Ořízněte to, co se vrací. Vracejte stručné výsledky s vysokou informační hodnotou místo surových API payloadů: Anthropic zdokumentoval zkrácení z 206 na 72 tokenů díky jedné změně response_format. Překládejte UUID na názvy, odstraňte pole, která model nikdy nepoužívá, a pamatujte, že každý výsledek nástroje znovu vstupuje do kontextového okna v každém následujícím kole. Méně volání díky atomickým nástrojům odstraní celé výsledky z účtu.

Jak vyhodnotím kvalitu volání nástrojů?

Skórujte čtyři metriky v pořadí: správnost nástroje (správný nástroj?), přesnost vstupu (platné argumenty?), dokončení úlohy (cíle dosaženo?) a efektivita úlohy (počet tokenů a volání?). Napište 15–30 úloh, každá očekávající jedno konkrétní volání s ověřitelnými argumenty a binární podmínkou průchodu. Spusťte sadu před a po každé změně nástroje, aby se přepsání popisu nikdy nenasadilo bez měření.

Závěr

Diagnostikujte, než optimalizujete. Váš agent vybírá špatný nástroj z jednoho ze čtyř důvodů a tři z osmi postupů výše, popisy, plochá schémata a filtrování, opravují selhání výběru, která způsobují většinu produkčních incidentů. Začněte tam, protože stojí jedno odpoledne a jsou důvodem, proč je tento problém vůbec řešitelný. Udržujte validační chyby informativní, chraňte cokoli destruktivního za člověkem a spouštějte evaluační smyčku při každé změně, abyste měřili, než vyměníte model. Problém špatného nástroje není problém modelu. Je to problém návrhu nástrojů a ten návrh vlastníte vy.