Deklarēt rīkus SDK
Šajā lapā
Deklarēt rīkus SDK
Rīki ir tava aģenta konkrētās spējas. Bez rīkiem aģents spēj tikai ģenerēt tekstu; ar rīkiem tas var vaicāt datubāzēm, izsaukt API un sūtīt e-pastus. Tomēr tie ir jādeklarē pareizi, jo rīka kvalitāte nav atkarīga tikai no koda – tā ir atkarīga arī no tā, cik labi modelis to saprot.
Dekorators @function_tool
Vienkāršākais veids, kā izveidot rīku, ir dekorators @function_tool, kas pārvērš standarta Python funkciju par spēju, ko aģents var izsaukt.
from agents import function_tool
@function_tool
def search_customer(email: str) -> str:
"""Meklē klientu pēc e-pasta adreses datubāzē.
Args:
email: Klienta e-pasta adrese, ko meklēt.
"""
# Produkcijā: izsauc savu datubāzi
customers = {
"[email protected]": {"name": "Alice Dupont", "plan": "Pro", "since": "2024"},
"[email protected]": {"name": "Bob Martin", "plan": "Starter", "since": "2025"},
}
customer = customers.get(email)
if customer:
return f"Klients atrasts: {customer['name']}, plāns {customer['plan']}, klients kopš {customer['since']}"
return f"Netika atrasts neviens klients ar e-pastu {email}"
Nekas netiek deklarēts divreiz: SDK izmanto funkcijas nosaukumu kā rīka nosaukumu, dokumentācijas virkni (docstring) kā aprakstu un tipu norādes, lai ģenerētu JSON shēmu parametriem. Citiem vārdiem, tava dokumentācijas virkne vairs nav tikai komentārs kolēģiem; tas ir teksts, ko modelis lasa, lai izlemtu, vai izsaukt šo funkciju. Neskaidra dokumentācijas virkne noved pie neprecīziem izsaukumiem.
Pielāgot nosaukumu un aprakstu
Ja tava funkcijas nosaukums atbilst iekšējām konvencijām, nevis biznesa loģikai, vari pārrakstīt to, ko redz modelis.
@function_tool(
name_override="search_crm",
description_override="Meklē klientu CRM sistēmā pēc e-pasta, vārda vai konta numura."
)
def search_customer(identifier: str) -> str:
"""Meklē klientu."""
# ...
return "Rezultāts"
Atbalstītie parametru tipi
Papildus natīvajiem Python tipiem SDK pieņem Pydantic modeļus. Kad rīks pieņem trīs vai vairāk parametrus, sagrupē tos: shēma kļūst lasāmāka modelim, un validācija pasargā tevi no ārkārtējām vērtībām.
from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool
class SearchFilter(BaseModel):
category: str = Field(description="Produkta kategorija")
max_price: Optional[float] = Field(None, description="Maksimālā cena eiro")
in_stock: bool = Field(True, description="Tikai produkti, kas ir noliktavā")
@function_tool
def search_products(filter: SearchFilter) -> str:
"""Meklē produktus, pamatojoties uz norādītajiem kritērijiem."""
results = []
# Meklēšanas loģika, izmantojot filter.category, filter.max_price utt.
return f"Atrasti {len(results)} produkti kategorijā {filter.category}"
Pydantic modeļi automātiski validē ievades datus un sniedz modelim bagātīgus, lauku pa laukam sniegtus aprakstus.
Atgriezt strukturētus rezultātus
Rīks vienmēr atgriež virkni. Ja taviem datiem ir struktūra – vairāki rādītāji, saraksts, jaukti tipi – serializē tos kā JSON, nevis veido teikumu: modelis nolasīs atslēgas daudz uzticamāk nekā brīvu tekstu.
import json
from agents import function_tool
@function_tool
def get_sales_stats(month: str, year: int) -> str:
"""Iegūst pārdošanas statistiku konkrētam mēnesim."""
stats = {
"month": month,
"year": year,
"revenue": 145000,
"sales_count": 342,
"avg_basket": 423.98,
"top_products": ["Laptop Pro", "Tablet Air", "Monitor 4K"]
}
return json.dumps(stats, ensure_ascii=False, indent=2)
OpenAI mitināti rīki
Papildus tavām pielāgotajām funkcijām SDK nodrošina piekļuvi OpenAI pārvaldītiem rīkiem, kas darbojas platformas pusē.
from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool
agent = Agent(
name="Vispārējas nozīmes asistents",
instructions="Tu esi asistents, kas spēj meklēt informāciju tīmeklī, analizēt failus un izpildīt kodu.",
tools=[
WebSearchTool(),
FileSearchTool(
vector_store_ids=["vs_abc123"],
max_num_results=10,
),
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
],
)
WebSearchTool ļauj aģentam meklēt informāciju internetā reāllaikā un neprasa nekādu konfigurāciju. FileSearchTool veic semantisko meklēšanu starp taviem failiem, taču pieņem iepriekšēju iestatīšanu: tev ir jāizveido vektoru krātuve, izmantojot OpenAI API, un tajā jāaugšupielādē savi dokumenti – tieši tāpēc parametrs ir vs_abc123. CodeInterpreterTool ļauj aģentam rakstīt un izpildīt Python kodu izolētā konteinerā, padarot to par galveno izvēli datu analīzei un diagrammu ģenerēšanai. Tam ir nepieciešams tool_config, kas norāda šo konteineru: {"type": "auto"} izveido to pēc pieprasījuma (SDK openai-agents noraida CodeInterpreterTool() bez tā).
Apvienot pielāgotus un mitinātus rīkus
Patiesā spēka slēpjas kombinācijā. Finanšu analītiķim ir nepieciešami tavi iekšējie dati, aprēķinu spējas un tirgus konteksts: trīs avoti, ko neaptver neviens viens rīks.
agent = Agent(
name="Finanšu analītiķis",
instructions="""Tu esi finanšu analītiķis.
Izmanto iekšējos rīkus datu iegūšanai,
koda interpretatoru to analīzei
un tīmekļa meklēšanu tirgus konteksta iegūšanai.""",
tools=[
get_sales_stats,
search_customer,
WebSearchTool(),
CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
],
)
Ievēro, kā instrukcijas precizē, kam paredzēta katra rīku saime. Bez šīs skaidrības aģents ar četriem rīkiem vilcinās, mēģinās divus nevajadzīgi un bez iemesla palielinās latentumu.
Galvenās atziņas
@function_toolpārvērš Python funkciju par aģenta rīku- Dokumentācijas virkne un tipu norādes automātiski ģenerē JSON shēmu
- Izmanto Pydantic sarežģītiem parametriem ar validāciju
- Rīki vienmēr atgriež virknes (JSON, ja dati ir strukturēti)
- Apvieno savus pielāgotos rīkus ar WebSearchTool, FileSearchTool un CodeInterpreterTool