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

Kehittyneet funktiokutsut: skeemat ja validointi

Oppitunti 7 / 25 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Kehittyneet funktiokutsut: skeemat ja validointi
  2. JSON-skeemat ja tiukka tila
  3. Mukautettu validointi Pydanticilla
  4. Virheiden käsittely työkaluissa
  5. Jäsennelty tuloste työkaluille
  6. Malli: jaetulla kontekstilla varustetut työkalut
  7. Keskeiset asiat

Kehittyneet funktiokutsut: skeemat ja validointi

Funktioikutsumekanismi on ydin, jonka avulla agentti päättää, milloin ja miten se kutsuu työkalujasi. Työkalun määrittely riittää prototyyppiin, mutta tuotantoon siirtyminen edellyttää kutsujen rajoittamista, liiketoiminta-arvojen validointia ja virheiden käsittelyä ilman, että agentti kaatuu. Tämä oppitunti käsittelee juuri näitä asioita.

JSON-skeemat ja tiukka tila

Responses API käyttää JSON-skeemoja kuvaamaan kunkin työkalun parametreja, ja tiukka (strict) tila takaa, että malli noudattaa skeemaa täsmällisesti. Erityisesti Enum- tai Literal-tyypin käyttö sulkee pois keksityt arvot.

from agents import function_tool
from pydantic import BaseModel, Field
from typing import Literal
from enum import Enum

class Priority(str, Enum):
    LOW = "low"
    MEDIUM = "medium"
    HIGH = "high"
    CRITICAL = "critical"

class CreateTicket(BaseModel):
    title: str = Field(description="Short ticket title (max 100 characters)")
    description: str = Field(description="Detailed problem description")
    priority: Priority = Field(description="Ticket priority level")
    component: Literal["frontend", "backend", "infra", "data"] = Field(
        description="Affected technical component"
    )
    tags: list[str] = Field(
        default_factory=list,
        description="Optional tags to categorize the ticket"
    )

@function_tool
def create_support_ticket(ticket: CreateTicket) -> str:
    """Creates a new technical support ticket."""
    # In production: call Jira, Linear, GitHub Issues, etc.
    return f"Ticket created: [{ticket.priority.value}] {ticket.title} ({ticket.component})"

Kun tiukka tila on oletusarvoisesti käytössä, malli ei voi koskaan lähettää virheellistä prioriteettia tai komponenttia, joka ei ole sallittujen listalla. Sinun ei tarvitse kirjoittaa puolustavaa backend-koodia muuntaaksesi arvoja kuten “urgent” tai “P1” sellaiseen muotoon, jonka lipunjärjestelmäsi tunnistaa.

Mukautettu validointi Pydanticilla

Tyyppitarkistus estää mahdottomat arvot, mutta ei absurdeja. Viidentoista merkin IBAN on täysin kelvollinen merkkijono, mutta liiketoimintalogiikkasi hylkää sen. Pydanticin avulla voit upottaa nämä säännöt suoraan skeemaan.

from pydantic import BaseModel, Field, field_validator

class MoneyTransfer(BaseModel):
    source_account: str = Field(description="Source account IBAN")
    destination_account: str = Field(description="Destination account IBAN")
    amount: float = Field(gt=0, le=50000, description="Amount in euros (max 50,000)")
    reason: str = Field(min_length=5, max_length=200, description="Reason for transfer")

    @field_validator("source_account", "destination_account")
    @classmethod
    def validate_iban(cls, v):
        if not v.startswith("FR"):
            raise ValueError("Only French IBANs are accepted")
        if len(v) != 27:
            raise ValueError("IBAN must contain 27 characters")
        return v

@function_tool
def execute_transfer(transfer: MoneyTransfer) -> str:
    """Executes a bank transfer between two accounts."""
    return f"Transfer of €{transfer.amount} initiated from {transfer.source_account[:8]}... to {transfer.destination_account[:8]}..."

Summaan kohdistuvat rajoitteet gt=0 ja le=50000 toimivat samalla tavalla eri tasolla: ne tekevät negatiivisesta siirrosta tai rajan ylittävästä siirrosta rakenteellisesti mahdottomia riippumatta siitä, miten käyttäjä muotoilee pyyntönsä.

Virheiden käsittely työkaluissa

Entä jos työkalu suoritetaan, mutta se epäonnistuu? Kiusaus on antaa poikkeuksen kuplia ylöspäin; tämä on virhe, koska se keskeyttää agentin silmukan. Sen sijaan palauta selkeä virheilmoitus, jonka malli voi lukea ja tulkita.

import json
from agents import function_tool

@function_tool
def query_external_api(endpoint: str, parameters: dict) -> str:
    """Queries an external API with the specified parameters."""
    try:
        # In production: real HTTP call
        import httpx
        response = httpx.get(f"https://api.example.com/{endpoint}", params=parameters, timeout=10)
        response.raise_for_status()
        return json.dumps(response.json(), ensure_ascii=False)
    except httpx.TimeoutException:
        return json.dumps({
            "error": True,
            "message": f"Timeout calling {endpoint}. Retry in a few moments."
        })
    except httpx.HTTPStatusError as e:
        return json.dumps({
            "error": True,
            "message": f"HTTP error {e.response.status_code} on {endpoint}.",
            "details": str(e)
        })
    except Exception as e:
        return json.dumps({
            "error": True,
            "message": f"Unexpected error: {str(e)}"
        })

Jokainen haara muotoilee viestin kielellä, jota malli ymmärtää. Aikakatkaisun sattuessa agentti yrittää uudelleenkutsua; HTTP 404 -virheen sattuessa se ilmoittaa käyttäjälle tai muuttaa lähestymistapaa sen sijaan, että jatkaisi sokeasti.

Jäsennelty tuloste työkaluille

Tämä rajoitus koskee myös lopullista tulostetta. Kun käytät output_type-parametria, final_output ei ole enää parsittavaa tekstiä, vaan tyypitetty objekti, jota kutsuva koodi voi käyttää suoraan.

from pydantic import BaseModel
from agents import Agent, Runner

class AnalysisResponse(BaseModel):
    summary: str
    key_points: list[str]
    recommendation: str
    confidence_score: float

agent = Agent(
    name="Analyst",
    instructions="Analyze the provided data and produce a structured report.",
    model="gpt-5.6-terra",
    output_type=AnalysisResponse,
)

result = Runner.run_sync(agent, "Analyze Q1 2026 sales trends.")
# result.final_output is of type AnalysisResponse
print(f"Summary: {result.final_output.summary}")
print(f"Score: {result.final_output.confidence_score}")

Malli: jaetulla kontekstilla varustetut työkalut

Yksi viimeinen toistuva ongelma: työkalusi tarvitsevat usein jaettua tilaa – kuten käyttäjäistunnon, tietokantayhteyden tai API-avaimen –, jonka välittäminen mallin kautta olisi absurdiä. Konteksti ratkaisee tämän välittämällä tiedot keskustelun mukana.

from dataclasses import dataclass
from agents import Agent, Runner, RunContextWrapper, function_tool

@dataclass
class AppContext:
    user_id: str
    db_connection: object  # Your DB connection
    api_key: str

@function_tool
def get_user_profile(ctx: RunContextWrapper[AppContext]) -> str:
    """Retrieves the current user's profile."""
    user_id = ctx.context.user_id
    # Use ctx.context.db_connection for the query
    return f"User profile {user_id}: Premium, active since 2024"

agent = Agent(
    name="Personalized Agent",
    instructions="You assist the logged-in user.",
    tools=[get_user_profile],
)

context = AppContext(user_id="usr_123", db_connection=None, api_key="xxx")
result = Runner.run_sync(agent, "What is my profile?", context=context)

Työkalulla ei ole liiketoimintaparametreja: käyttäjän identiteetti tulee kontekstista, ei mallilta. Tämä on myös turvallisuustoimenpide, sillä agentti ei voi tarkastella toisen henkilön profiilia muuttamalla argumenttia.

Keskeiset asiat

  • Enumeja ja Literaleja sisältävät Pydantic-skeemat takaavat kutsujen validiteetin
  • Kenttävalidaattorit lisäävät liiketoimintatason validoinnin tyyppitarkistuksen päälle
  • Palauta JSON-muotoiset virheilmoitukset työkaluissa poikkeusten heittämisen sijaan
  • output_type pakottaa agentin jäsentelemään lopullisen vastauksensa
  • Jaettu konteksti (RunContextWrapper) mahdollistaa työkalujen pääsyn sovellustilaan