Claude Architect · Oppitunti

Agentin määrittäminen

name, description, system_prompt ja allowed_tools.

Oppitunti 2/413 vaihetta

Agentin määrittäminen 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.

Mikä agenttimäärittely on

Agentti Claude Agent SDK:ssa ei ole taikuutta. Se on pieni, eksplisiittinen määritys, joka kertoo mallille, kuka se on ja mitä se saa tehdä.

AgentDefinition-määrittelyllä on neljä keskeistä kenttää:

name — lyhyt tunniste, jota käytetään työn reitittämiseen tälle agentille
description — mihin tätä agenttia käytetään (sen perusteella koordinaattori päättää delegoinnista)
system_prompt — pysyvät ohjeet, jotka ohjaavat toimintaa
allowed_tools — täsmällinen joukko työkaluja, joita agentti saa kutsua

Kun nämä neljä ovat kunnossa, agentti toimii ennakoitavasti. Jos ne ovat pielessä, seurauksena on virhereititystä, vastuualueen laajenemista ja epäluotettavaa työkalujen valintaa.

Määrittelyn rakenne

Tässä on agenttimäärittelyn pienin runko. Huomaatte, että jokaisella kentällä on merkitystä: mikään tässä ei ole koristeellista.

allowed_tools-luettelo noudattaa vähimpien oikeuksien periaatetta — myöntäkää vain ne työkalut, joita rooli todella tarvitsee.

agent = AgentDefinition(
    name="refund_specialist",
    description=(
        "Handles customer refund requests after identity "
        "verification. Use for billing disputes and order "
        "cancellations."
    ),
    system_prompt=(
        "You are a careful refund specialist. Always verify "
        "the customer's identity before processing anything."
    ),
    allowed_tools=["get_customer", "lookup_order", "process_refund"],
)

name — reititysavain

name on pysyvä tunniste. Monen agentin hub-and-spoke-järjestelmässä koordinaattori reitittää työn aliagenteille, ja nimen avulla tietty agentti osoitetaan.

Pidä nimet lyhyinä, pienillä kirjaimilla kirjoitettuina ja roolipohjaisina: research_agent, code_reviewer, refund_specialist.

Muistakaa kuitenkin tärkeä koetilanteessa tarvittava fakta: nimet EIVÄT ole ensisijainen valintamekanismi. Kun malli päättää, käyttääkö se työkalua tai agenttia, se tukeutuu kuvaukseen, ei nimeen. Selkeä nimi auttaa siis ihmisiä, mutta varsinainen reititys perustuu kuvaukseen.

description — miten delegointi tapahtuu

description on kenttä, jonka perusteella koordinaattori päättää, milloin työ annetaan tälle agentille. Se on oikean reitityksen kannalta tärkein yksittäinen kenttä.

Hyvä kuvaus kertoo seuraavat asiat:

Tarkoitus — mitä agentti tekee
Sovellettavuuden rajat — milloin sitä käytetään ja milloin sitä EI käytetä

Agenttien epämääräiset tai päällekkäiset kuvaukset aiheuttavat virhereititystä: koordinaattori valitsee väärän asiantuntijan. Muotoile jokaisen agentin kuvaus erottuvaksi, jotta ei ole epäselvyyttä siitä, kenelle mikäkin tehtävä kuuluu.

research_agent = AgentDefinition(
    name="research_agent",
    description=(
        "Searches the web and summarizes findings WITH citations "
        "for open-ended factual questions. Do NOT use for code "
        "changes or refunds."
    ),
    system_prompt="You are a meticulous research assistant...",
    allowed_tools=["WebSearch", "WebFetch"],
)

system_prompt — pysyvä toiminta

system_prompt määrittää agentin pysyvän identiteetin ja säännöt. Se säilyy agenttisilmukan jokaisella vuorolla, joten sijoittakaa pysyvät toimintatakuut tähän.

Kirjoittakaa eksplisiittisiä ehtoja, älkää epämääräisiä kehotuksia. Verratkaa:

Epämääräinen: "Be careful with refunds."
Eksplisiittinen: "Never call process_refund until get_customer has returned a verified customer ID."

Eksplisiittiset ohjeet toimivat johdonmukaisesti paremmin kuin epämääräiset. Malli pystyy toimimaan konkreettisen säännön perusteella, mutta se ei pysty luotettavasti toimimaan ohjeella "ole varovaisempi".

system_prompt = (
    "You are a refund specialist.\n"
    "- Always call get_customer FIRST and confirm a verified ID.\n"
    "- Only refund the exact order the customer names.\n"
    "- If multiple customers match, ask for more identifiers; "
    "never guess."
)

Kehotteet ovat probabilistisia

Tässä on hienovarainen mutta kokeen kannalta ratkaiseva asia. system_prompt ohjaa toimintaa — mutta ohjaus on luotettavaa noin 90-prosenttisesti, ei sataprosenttisesti.

Jos säännöllä on taloudellisia, oikeudellisia tai turvallisuuteen liittyviä seurauksia, ÄLKÄÄ luottako pelkkään kehotteeseen. Valvokaa sääntöä deterministisesti hookilla.

Kehote: "Don't refund more than $500" — toimii useimmiten (noin 90 %).
Hook: PostToolUse- tai lähtevän kutsun hook, joka estää kaikki yli 500 dollarin hyvitykset — toimii 100-prosenttisesti.

Sijoittakaa siis toimintaohjeet system_prompt-kenttään, mutta tiukat takuut hookeihin. Agentin hyvä määrittely edellyttää sen tietämistä, mitkä säännöt kuuluvat mihinkin.

allowed_tools — vähimmät oikeudet

allowed_tools-kenttä rajaa täsmälleen, mitä työkaluja agentti voi käyttää. Tämä on ensisijainen turvarajanne: agentti ei yksinkertaisesti voi kutsua työkalua, joka ei ole sen luettelossa.

Rajaa työkalut roolin mukaan. Hyvitysagentti ei tarvitse WebSearch-työkalua, eikä tutkimusagentti tarvitse process_refund-työkalua. Ylimääräisten työkalujen myöntäminen ei ole mukavuutta — se lisää riskejä ja heikentää valinnan tarkkuutta.

# Least privilege: each agent sees only its own tools
support_agent.allowed_tools = [
    "get_customer", "lookup_order",
    "process_refund", "escalate_to_human",
]
# NOT: every tool in the system

Kuinka monta työkalua on sopiva määrä?

Työkalujen suurempi määrä ei ole parempi. Työkalujen valinnan luotettavuudella on optimaalinen alue:

4–5 työkalua agenttia kohden on optimaalinen määrä.
Yli 18 työkalua heikentää valintaa mitattavasti — malli reitittää väärin liian monien samankaltaisten vaihtoehtojen välillä.

Jos agentin allowed_tools-luettelo alkaa venyä pitkäksi, kyse on suunnitteluongelman merkistä. Jakakaa työ keskittyneille aliagenteille, joilla kullakin on rajattu työkalujoukko ja erottuva kuvaus. Kapea vastuualue tekee kustakin agentista luotettavan.

Työkalujen kuvaukset ohjaavat valintaa

Agentin työkalujen määrittely on vasta puolet työstä; kunkin työkalun kuvauksen määrittely on toinen puoli. Työkalujen kuvaukset — eivät nimet — kertovat mallille, mikä työkalu kutsutaan.

Hyvä työkalun kuvaus sisältää seuraavat:

tarkoitus
palautettavat arvot
syötemuodot esimerkkeineen
reunatapaukset ja sovellettavuuden rajat

Päällekkäiset tai epäselvät työkalukuvaukset aiheuttavat saman virhereititysongelman kuin epäselvät agenttikuvaukset, mutta yhtä tasoa alempana.

{
  "name": "lookup_order",
  "description": "Fetch an order by its ID. Input: order_id like 'ORD-10293'. Returns status, items, and total. Use AFTER get_customer verifies identity. Returns an empty result (not an error) if no order matches.",
  "input_schema": {
    "type": "object",
    "properties": {"order_id": {"type": "string"}},
    "required": ["order_id"]
  }
}

Koordinaattori tarvitsee Task-työkalun

Kun määrittelette koordinaattorin hub-and-spoke-järjestelmään, se delegoi tehtäviä aliagenteille. Jotta tämä toimisi, koordinaattorin allowed_tools-luettelon on sisällettävä "Task" — se on työkalu, jolla aliagentit käynnistetään.

Yksi tärkeä lisätieto: aliagentit EIVÄT peri koordinaattorin keskusteluhistoriaa. Jokainen aliagentti aloittaa puhtaalta pöydältä, joten kaikki tarvittava konteksti on välitettävä eksplisiittisesti aliagentin kehotteessa. Määrittely hallitsee kyvykkyyksiä, ja delegointihetken kehote hallitsee kontekstia.

coordinator = AgentDefinition(
    name="coordinator",
    description="Decomposes the request and delegates to specialists.",
    system_prompt="Break the task into subtasks. Pass ALL needed context to each subagent explicitly.",
    allowed_tools=["Task"],  # required to delegate
)

Kokonaisuuden yhdistäminen

Hyvin määritelty agentti muistuttaa lähes työpaikkailmoitusta:

name: pysyvä reititystunniste
description: täsmällinen tarkoituksen ja rajojen kuvaus, jotta koordinaattori delegoi oikein
system_prompt: eksplisiittiset, pysyvät toimintasäännöt (probabilistiset — yhdistäkää niihin hookit tiukkoja takuita varten)
allowed_tools: rajattu, vähimpien oikeuksien mukainen joukko, mieluiten 4–5 työkalua, joilla kullakin on kattava kuvaus

Kun kaikki neljä ovat tarkasti määriteltyjä eivätkä mene päällekkäin, agentti hoitaa yhden tehtävän hyvin. Se on perusta, jolle jokainen monen agentin arkkitehtuuri rakennetaan.

Pikatarkistus

Tilannepohjainen päätös agentin määrittelystä.

Vastaa interaktiivisessa oppitunnissa

Kertaus: agentin määrittely

Tärkeimmät opit:

AgentDefinition = name, description, system_prompt, allowed_tools.
description (ei name) ohjaa delegointia sekä työkalun/agentin valintaa — pitäkää se täsmällisenä ja ei-päällekkäisenä.
system_prompt määrittää pysyvän, eksplisiittisen toiminnan, mutta on luotettava vain noin 90-prosenttisesti; valvokaa talous-, laki- ja turvallisuussääntöjä hookeilla (100-prosenttisen deterministisesti).
allowed_tools = vähimmät oikeudet; tavoitelkaa 4–5 työkalua, sillä yli 18 heikentää valintaa. Jokainen työkalu tarvitsee kattavan kuvauksen.
Koordinaattorin on sisällytettävä "Task" allowed_tools-luetteloon, eivätkä aliagentit peri historiaa — välittäkää konteksti eksplisiittisesti.

Määritelkää vastuualueet kapeiksi ja kuvaukset selkeiksi, niin jokainen rakentamanne agentti toimii ennakoitavasti.

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 ”Agentin määrittäminen” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa Claude Architect-oppimispolun 3 oppituntia, myös oppitunnin “Agentin määrittäminen”. 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 ”Agentin määrittäminen”?

name, description, system_prompt ja allowed_tools. 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 ”Agentin määrittäminen”-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