Kehittyneet funktiokutsut: skeemat ja validointi
Tällä sivulla
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_typepakottaa agentin jäsentelemään lopullisen vastauksensa- Jaettu konteksti (
RunContextWrapper) mahdollistaa työkalujen pääsyn sovellustilaan