Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Monivaiheinen agentti päättelysilmukalla

Oppitunti 15 / 25 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Monivaiheinen agentti päättelysilmukalla
  2. Suunnittele-suorita-malli
  3. Itseään korjaava agentti
  4. Malli: erikoistuneiden agenttien ketju
  5. Päättelyn syvyyden hallinta
  6. Keskeiset asiat

Monivaiheinen agentti päättelysilmukalla

Tehokkaimmat agentit eivät pysähdy yhden työkalukutsun jälkeen. Ne ketjuttavat useita päättelyvaiheita, mukauttavat strategiaansa tulosten perusteella ja toistavat prosessia, kunnes saavuttavat tavoitteensa. Tässä oppitunnissa opit rakentamaan tällaisia monivaiheisia agentteja. Esimerkit käyttävät GPT-5.6 -perhettä: kun edellinen sukupolvi vaati mallin vaihtamista päättelyn mahdollistamiseksi, voit nyt hallita tätä käyttäytymistä valitsemasi mallin effort-asetuksella.

Suunnittele-suorita-malli

Monivaiheinen agentti aloittaa luomalla suunnitelman ja suorittaa sitten jokaisen vaiheen. Tämä erottelu on tarkoituksellista: suunnittelijalla ei ole työkaluja, ja se tuottaa tyypitetyn rakenteen, kun taas suorittaja vastaanottaa tämän suunnitelman tiekartaksi ja yksinkertaisesti noudattaa sitä. Epämääräinen pyyntö, kuten “valmistele vuosineljänneksen katsaus avainasiakkaille”, muuttuu konkreettiseksi toimintasarjaksi – kysy CRM-järjestelmästä, luo raportti, lähetä sähköposti – ennen kuin mitään toimintaa yritetään.

from agents import Agent, Runner, function_tool
from pydantic import BaseModel
import json

class PlanAction(BaseModel):
    steps: list[str]
    objective: str

planner_agent = Agent(
    name="Planner",
    instructions="""You receive a complex task. Break it down into simple, ordered steps.
    Each step must be a concrete, actionable item.""",
    model="gpt-5.6-sol",  # Advanced reasoning for planning
    output_type=PlanAction,
)

@function_tool
def search_crm(query: str) -> str:
    """Searches the CRM for customer information."""
    return json.dumps({"customers": [
        {"name": "Acme Corp", "revenue": 500000, "contract": "Enterprise"},
        {"name": "TechStart", "revenue": 50000, "contract": "Starter"},
    ]})

@function_tool
def generate_report(title: str, content: str) -> str:
    """Generates a formatted report."""
    return f"Report '{title}' generated successfully ({len(content)} characters)"

@function_tool
def send_email(recipient: str, subject: str, body: str) -> str:
    """Sends an email."""
    return f"Email sent to {recipient}: {subject}"

executor_agent = Agent(
    name="Executor",
    instructions="""You execute tasks step by step.
    Use available tools to complete each step.
    If a step fails, try an alternative approach.""",
    tools=[search_crm, generate_report, send_email],
    model="gpt-5.6-terra",
)

async def process_complex_task(task: str):
    # Step 1: Plan
    plan = await Runner.run(planner_agent, task)
    print(f"Plan: {plan.final_output.steps}")

    # Step 2: Execute with the plan as context
    execution_instructions = f"""Execute the following steps in order:
    {chr(10).join(f'{i+1}. {e}' for i, e in enumerate(plan.final_output.steps))}
    Objective: {plan.final_output.objective}"""

    result = await Runner.run(executor_agent, execution_instructions)
    return result.final_output

Itseään korjaava agentti

Pelkkä suunnittelu ei riitä: todellisessa maailmassa työkalut epäonnistuvat. Toinen silmukkatyyppi antaa agentille mahdollisuuden havaita omat virheensä ja korjata ne. Kaikki riippuu usein huomiotta jääneestä yksityiskohdasta: työkalu ei heitä poikkeusta, vaan palauttaa luettavan virheilmoituksen. Agentti lukee sen, huomaa unohtaneensa FROM-lausekkeen, kirjoittaa kyselyn uudelleen ja yrittää uudelleen ohjeistuksessa määritetyn kolmen yrityksen rajan puitteissa.

from agents import Agent, Runner, function_tool

@function_tool
def execute_sql_query(sql: str) -> str:
    """Executes an SQL query on the database."""
    # Simulation: some queries fail
    if "DROP" in sql.upper():
        return "ERROR: Destructive queries are forbidden."
    if "SELECT" in sql.upper() and "FROM" not in sql.upper():
        return "ERROR: Invalid SQL syntax - missing FROM."
    return json.dumps({
        "columns": ["name", "monthly_revenue", "region"],
        "rows": [
            ["Acme Corp", 45000, "Île-de-France"],
            ["TechStart", 12000, "Rhône-Alpes"],
        ],
        "result_count": 2
    })

analyst_agent = Agent(
    name="Data Analyst",
    instructions="""You analyze data by executing SQL queries.
    If a query fails:
    1. Analyze the error message
    2. Correct the query
    3. Retry
    Maximum 3 attempts per query.
    Never use DROP, DELETE, or TRUNCATE.""",
    tools=[execute_sql_query],
    model="gpt-5.6-terra",
    max_turns=10,  # Enough turns for corrections
)

result = Runner.run_sync(
    analyst_agent,
    "What is the total revenue by region?"
)

Huomaa, että tuhoavien kyselyjen kielto esiintyy kahdessa paikassa: ohjeistuksessa ja työkalun koodissa. Ohjeistus opastaa mallia, mutta vain palvelinpuolen tarkistus työkalussa takaa, ettei DROP TABLE -komento koskaan pääse läpi.

Malli: erikoistuneiden agenttien ketju

Monimutkaisissa työkuluissa ketjuta useita erikoistuneita agentteja sen sijaan, että lataisit kaikki vastuut yhdelle agentille. Jokaisella lenkillä on selkeä rooli: kerääjä hankkii raaka-aineen, analyytikko – varustettuna päättelymallilla – tunnistaa trendit ja kirjoittaja muotoilee lopputuloksen. Hyöty on sekä opetuksellinen että operatiivinen: kun loppuraportti pettää odotukset, tiedät välittömästi, kumpaa kolmesta agentista pitää korjata.

from agents import Agent, Runner

collection_agent = Agent(
    name="Data Collector",
    instructions="Collect all data necessary for the analysis.",
    tools=[search_crm, execute_sql_query],
    model="gpt-5.6-terra",
)

analysis_agent = Agent(
    name="Analyst",
    instructions="Analyze the collected data and identify trends.",
    model="gpt-5.6-sol",  # Advanced reasoning for analysis
)

writing_agent = Agent(
    name="Writer",
    instructions="""Write a clear, structured report in English
    based on the provided analysis. Format: introduction, key points, recommendations.""",
    model="gpt-5.6-terra",
)

async def analysis_pipeline(question: str):
    # Step 1: Collect data
    data = await Runner.run(collection_agent, question)

    # Step 2: Analyze
    analysis = await Runner.run(
        analysis_agent,
        f"Analyze this data: {data.final_output}"
    )

    # Step 3: Write the report
    report = await Runner.run(
        writing_agent,
        f"Write a report based on this analysis: {analysis.final_output}"
    )

    return report.final_output

Päättelyn syvyyden hallinta

Kaikilla näillä silmukoilla on yksi yhteinen piirre: ne eivät välttämättä koskaan pysähdy. Parametri max_turns on ensisijainen suojauksesi, ja säädät sitä tehtävän vaativuuden mukaan. Kolme kierrosta riittää agentille, jonka odotetaan vastaavan ensimmäisellä yrityksellä; kaksikymmentäviisi tarvitaan tutkimukseen, joka kysyy useista lähteistä ennen johtopäätöksen tekemistä.

# Conservative agent: few turns
simple_agent = Agent(
    name="Simple Agent",
    instructions="Answer in a single turn if possible.",
    model="gpt-5.6-terra",
)
result = await Runner.run(simple_agent, "Simple question", max_turns=3)

# Complex agent: many turns
research_agent = Agent(
    name="Deep Researcher",
    instructions="Explore all angles before concluding.",
    tools=[search_crm, execute_sql_query],
    model="gpt-5.6-terra",
)
result = await Runner.run(research_agent, "Complete Q1 analysis", max_turns=25)

Aseta tämä arvo tarkkailemalla jälkiäsi arvaamisen sijaan: jos todelliset suorituksesi päättyvät kuudessa kierroksessa, rajana oleva kaksikymmentäviisi ei suojaa miltään.

Keskeiset asiat

  • Suunnittele-suorita-malli erottaa suunnittelun (päättelymalli) suorittamisesta
  • Itseään korjaava agentti analysoi virheitään ja mukauttaa strategiaansa
  • Erikoistuneiden agenttien ketjut mahdollistavat monimutkaiset ja ylläpidettävät työkulut
  • max_turns hallitsee päättelyn syvyyttä ja suojaa äärettömiltä silmukoilta
  • Varaa edistyneet päättelyominaisuudet suunnitteluun ja analyysiin