Claude Architect · Oppitunti

tool_choice: auto / any / forced

Anna mallin valita, pakota työkalu tai kiinnitä valinta nimettyyn työkaluun.

Oppitunti 2/413 vaihetta

tool_choice: auto / any / forced on ilmainen Claude Architect-oppitunti CoddyKitissä. Tämä on oppitunti 2/4. Voit lukea tästä oppimispolusta kokonaan mitkä tahansa 3 oppituntia ilmaiseksi — sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä käytännön harjoittelun sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Oppitunti kuuluu Claude Architect-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Claude Architect-kurssilla on yhteensä 4 oppituntia.

Kuka päättää: malli vai Te?

Kun annatte Claudelle työkaluja, yksi kysymys ohjaa koko vuorovaikutusta: kuka päättää, suoritetaanko työkalu?

API-pyynnön tool_choice-kenttä antaa vastauksen. Voitte antaa mallin päättää, pakottaa sen kutsumaan jotakin työkalua tai lukita yhden tietyn työkalun nimen perusteella.

Oikea valinta on olennainen osa työkalujen jakamista: väärä asetus tuottaa jutustelevaa tekstiä silloin, kun tarvitsitte rakenteista dataa, tai pakotetun työkalukutsun silloin, kun mallin olisi pitänyt vain vastata.

Kolme tilaa

tool_choice-kentällä on kolme mahdollista arvoa:

auto — malli valitsee vapaasti: tuottaa tekstiä tai kutsuu työkalua.
any — mallin on kutsuttava jotakin työkalua (se saa itse valita minkä), joten vuoro palauttaa työkalukutsun eikä koskaan vapaata tekstiä.
{"type":"tool","name":"X"} — pakottaa käyttämään yhtä tiettyä nimettyä työkalua.

Kukin vastaa eri tarkoitusta: joustavaa päättelyä, taattua rakenteista tulostetta tai tiukasti lukittua toimintoa.

request = {
    "model": "claude-sonnet-4-5",
    "max_tokens": 1024,
    "tools": tools,
    "tool_choice": {"type": "auto"},  # or "any", or a named tool
    "messages": messages,
}

auto: anna mallin valita

auto on agenttisilmukoiden oletusvalinta. Malli tarkastelee keskustelua ja päättää itse, tarvitaanko työkalua vai riittääkö tavallinen tekstivastaus.

Käyttäkää sitä, kun etenemispolku on avoin: tukipalveluagentti voi vastata kysymykseen suoraan tai joutua ensin hakemaan tilauksen tiedot.

auto-tilassa pysäytyssyy kertoo, mitä tapahtui: tool_use tarkoittaa, että työkalu suoritetaan ja silmukkaa jatketaan; end_turn tarkoittaa, että malli vastasi tekstillä ja on valmis.

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=tools,
    tool_choice={"type": "auto"},
    messages=messages,
)

if resp.stop_reason == "tool_use":
    # run the requested tool(s), append results, loop again
    ...
elif resp.stop_reason == "end_turn":
    # model replied with text; turn complete
    ...

any: takaa työkalukutsun

any pakottaa mallin kutsumaan jotakin työkalua jokaisella vuorolla — se ei voi vastata vapaamuotoisella tekstillä. Se valitsee edelleen minkä työkalun kutsuu, mutta työkalukutsu taataan.

Tämä on klassinen keino saada taattu rakenteinen tuloste: jos ainoa työkalunne on skeeman mukainen record_result, any tarkoittaa, että jokainen vastaus palautuu validoituina JSON-argumentteina eikä jäsentämättömänä kappaleena.

classify_tool = {
    "name": "record_sentiment",
    "description": "Record the sentiment of a customer message.",
    "input_schema": {
        "type": "object",
        "properties": {
            "sentiment": {"type": "string",
                          "enum": ["positive", "neutral", "negative"]}
        },
        "required": ["sentiment"],
    },
}

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=512,
    tools=[classify_tool],
    tool_choice={"type": "any"},  # must call a tool -> structured output
    messages=messages,
)

Pakotettu: lukitse yksi työkalu nimen perusteella

Täsmällisin tila pakottaa käyttämään täsmälleen yhtä työkalua: {"type":"tool","name":"X"}. Malli ei voi valita, minkä työkalun se kutsuu — se voi ainoastaan täyttää sen argumentit.

Käyttäkää tätä, kun toiminto on jo päätetty ja tarvitsette vain mallin poimimaan parametrit. Esimerkiksi tiedätte, että tämän vuoron on tuotettava poimintatietue, joten lukitsette työkalun extract_invoice ja annatte Clauden täyttää kentät.

resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=1024,
    tools=[extract_invoice_tool],
    tool_choice={"type": "tool", "name": "extract_invoice"},
    messages=[{"role": "user", "content": invoice_text}],
)

# resp.content[0] is a tool_use block with the extracted fields
fields = resp.content[0].input

any ja pakotettu: hienovarainen ero

Sekä any että pakotettu tila takaavat työkalukutsun. Ero on valinnassa:

any — malli valitsee edelleen työkalujoukosta, mitä työkalua käytetään. Sopii, kun useat työkalut ovat kelvollisia ja haluatte rakenteisen tulosteen mutta joustavan reitityksen.
pakotettu {"type":"tool","name":"X"} — reitityspäätöstä ei ole lainkaan; työkalu X suoritetaan.

Nyrkkisääntö: jos olette jo tehneet päätöksen koodissa, pakottakaa työkalu. Jos mallin pitäisi edelleen päättää, mikä rakenteinen toiminto sopii, käyttäkää any-tilaa.

Rakenteinen tuloste on suurin hyöty

JSON Schema -työkalun yhdistäminen any-tilaan tai pakotettuun työkaluun on tapa saada luotettava rakenteinen tuloste. Skeema poistaa syntaksivirheet ja varmistaa pakolliset kentät — hauraalle tekstin säännöllisiin lausekkeisiin perustuvalla käsittelylle ei ole tarvetta.

Yksi skeemaa koskeva sääntö on tässä tärkeä: merkitkää kenttä required-kentäksi vain, jos se on aina mukana. Älkää koskaan vaatiko kenttää, joka saattaa puuttua — malli keksii sille arvon täyttääkseen skeeman vaatimukset.

extract_invoice_tool = {
    "name": "extract_invoice",
    "description": "Extract structured fields from an invoice document.",
    "input_schema": {
        "type": "object",
        "properties": {
            "invoice_number": {"type": "string"},
            "total": {"type": "number"},
            "due_date": {"type": "string"},  # may be absent -> NOT required
        },
        # only fields that are ALWAYS present belong here
        "required": ["invoice_number", "total"],
    },
}

auto pitää agenttisilmukan käynnissä

Monivaiheisessa agentissa auto on yleensä oikea valinta, koska silmukka on malliohjattu. Lähetätte koko historian jokaisella vuorolla, luette stop_reason-arvon, suoritatte pyydetyt työkalut, lisäätte tulokset ja toistatte tämän, kunnes malli tuottaa arvon end_turn.

Jos pakottaisitte työkalun jokaisella vuorolla, malli ei voisi koskaan ilmoittaa tekstillä olevansa valmis, eikä silmukalla olisi luontevaa päätepistettä. Käyttäkää pakottamista vain yksittäisiin, ennalta päätettyihin toimintoihin.

while True:
    resp = client.messages.create(
        model="claude-sonnet-4-5",
        max_tokens=1024,
        tools=tools,
        tool_choice={"type": "auto"},
        messages=messages,
    )
    messages.append({"role": "assistant", "content": resp.content})
    if resp.stop_reason == "tool_use":
        results = run_tools(resp.content)
        messages.append({"role": "user", "content": results})
        continue
    break  # end_turn -> terminate on stop_reason, never on text

Älä sekoita valintaa pakottamiseen

tool_choice määrittää, kutsutaanko työkalua — se ei valvo liiketoimintasääntöjä. process_refund-työkalun pakottaminen ei takaa, että hyvitys on sallittu.

Kriittiset takuut (henkilöllisyys on vahvistettu, hyvitys alittaa käytännön enimmäisrajan) kuuluvat deterministisiin esiehtoihin ja koukkuihin, jotka ovat sataprosenttisen luotettavia, eivät tool_choice-asetukseen tai kehotetekstiin (noin 90-prosenttisesti todennäköisiä).

Ajatelkaa tool_choice-asetusta reitityksenä ja koukkuja/esiehtoja suojakaiteina.

Kuvaus ohjaa edelleen valintaa

Myös auto- tai any-arvolla mallin työkalun valinta riippuu työkalujen kuvauksista, ei nimistä. Hyvä kuvaus kertoo tarkoituksen, palautettavat arvot, syötemuodot esimerkkeineen, poikkeustapaukset ja käyttöalueen rajat.

Toisiaan sivuavat tai epämääräiset kuvaukset johtavat vääriin reitityksiin, joita mikään tool_choice-arvo ei voi korjata. Pitäkää kullakin agentilla noin 4–5 tarkasti rajattua työkalua; yli 18 työkalua heikentää valinnan luotettavuutta.

tool_choice määrittää käytännön; kuvaukset tekevät reitityksestä täsmällistä.

Käytännöllinen päätösopas

Valitkaa käyttötarkoituksen perusteella:

auto — avoimet agentin vuorot; malli voi vastata tekstillä tai toimia. Agentin toimintasilmukan oletusasetus.
any — tarvitsette rakenteisen tulosteen, mutta useampi työkalu voi sopia tilanteeseen; malli reitittää pyynnön niiden välillä.
forced (name) — toiminto on jo päätetty; tarvitsette vain argumenttien poiminnan (luokittelu, yksittäinen poiminta).

Jos olette tehneet päätöksen koodissa, pakottakaa valinta. Jos mallin pitäisi päätellä, tarvitaanko työkalua ja mikä työkalu sopii, käyttäkää auto- tai any-arvoa.

# Single-shot classification: decision already made -> force it
resp = client.messages.create(
    model="claude-sonnet-4-5",
    max_tokens=256,
    tools=[record_sentiment_tool],
    tool_choice={"type": "tool", "name": "record_sentiment"},
    messages=[{"role": "user", "content": review_text}],
)
sentiment = resp.content[0].input["sentiment"]

Pikatarkistus

Valitkaa alla olevaan tilanteeseen parhaiten sopiva tool_choice.

Vastaa interaktiivisessa oppitunnissa

Kertaus: valitse, takaa tai lukitse

Tärkeimmät opit:

auto — malli valitsee tekstin tai työkalun; oletus malliohjatuissa agentin toimintasilmukoissa, joiden on voitava ilmoittaa end_turn.
any — jonkin työkalun kutsuminen on pakollista; tällä taataan rakenteinen tuloste ja säilytetään joustava reititys.
{"type":"tool","name":"X"} — lukitsee valinnan yhteen työkaluun; käyttäkää tätä, kun toiminto on päätetty ja tarvitsette vain argumenttien poiminnan.
tool_choice huolehtii reitityksestä, ei pakottamisesta — sijoittakaa kriittiset takuut hookeihin ja esiehtoihin.
Täsmällinen valinta riippuu edelleen hyvistä työkalujen kuvauksista ja 4–5 tarkasti rajatusta työkalusta agenttia kohden.

Aloita maksutta

Opi Python tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 26
Oppitunnit: 104

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”tool_choice: auto / any / forced” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa Claude Architect-oppimispolun 3 oppituntia, myös oppitunnin “tool_choice: auto / any / forced”. Sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä interaktiiviset harjoitukset sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Claude Architect-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”tool_choice: auto / any / forced”?

Anna mallin valita, pakota työkalu tai kiinnitä valinta nimettyyn työkaluun. Harjoittelet Claude Architect-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni Claude Architect-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin Claude Architect-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 2/4.

Kuinka kauan ”tool_choice: auto / any / forced”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä Claude Architect-oppitunnilla?

Kyllä. Jokainen Claude Architect-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

← Takaisin: Claude Architect