Премини към основното съдържание
Български— Изберете език
Меню

Деклариране на инструменти в SDK

Урок 6 от 25 Обновен 2 ноември 2026 г. Програмист
На тази страница
  1. Деклариране на инструменти в SDK
  2. Декораторът @function_tool
  3. Персонализиране на име и описание
  4. Поддържани типове параметри
  5. Връщане на структурирани резултати
  6. Инструменти, хоствани от OpenAI
  7. Комбиниране на персонализирани и хоствани инструменти
  8. Ключови изводи

Деклариране на инструменти в SDK

Инструментите са конкретните възможности на Вашия агент. Без тях агентът може само да генерира текст; с тях той може да заявява бази данни, да извиква API и да изпраща имейли. Трябва обаче да ги декларирате правилно, защото качеството на един инструмент не зависи единствено от кода му, а и от това колко добре моделът го разбира.

Декораторът @function_tool

Най-простият начин за създаване на инструмент е декораторът @function_tool, който превръща стандартна Python функция във възможност, която агентът може да извика.

from agents import function_tool

@function_tool
def search_customer(email: str) -> str:
    """Search for a customer by email address in the database.

    Args:
        email: The customer's email address to search for.
    """
    # In production: call your database
    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"Customer found: {customer['name']}, plan {customer['plan']}, customer since {customer['since']}"
    return f"No customer found with email {email}"

Нищо не се декларира два пъти: SDK използва името на функцията като име на инструмента, docstring-а като описание и type hints-овете за генериране на JSON схемата за параметрите. С други думи, Вашият docstring вече не е просто коментар за колегите Ви; това е текстът, който моделът чете, за да реши дали да извика тази функция. Неясен docstring води до неточни извиквания.

Персонализиране на име и описание

Когато името на Вашата функция следва вътрешни конвенции, а не бизнес логиката, можете да промените това, което моделът вижда.

@function_tool(
    name_override="search_crm",
    description_override="Search for a customer in the CRM by email, name, or account number."
)
def search_customer(identifier: str) -> str:
    """Search for a customer."""
    # ...
    return "Result"

Поддържани типове параметри

Освен вградените Python типове, SDK приема и Pydantic модели. Когато един инструмент приема три или повече параметъра, групирайте ги: схемата става по-четима за модела, а валидацията Ви предпазва от стойности извън очаквания диапазон.

from pydantic import BaseModel, Field
from typing import Optional
from agents import function_tool

class SearchFilter(BaseModel):
    category: str = Field(description="Product category")
    max_price: Optional[float] = Field(None, description="Maximum price in euros")
    in_stock: bool = Field(True, description="Only products in stock")

@function_tool
def search_products(filter: SearchFilter) -> str:
    """Search for products based on specified criteria."""
    results = []
    # Search logic using filter.category, filter.max_price, etc.
    return f"Found {len(results)} products in {filter.category}"

Pydantic моделите автоматично валидират входните данни и предоставят на модела богати описания поле по поле.

Връщане на структурирани резултати

Един инструмент винаги връща низ. Когато Вашите данни имат структура – множество метрики, списък, смесени типове – сериализирайте ги като JSON, вместо да съставяте изречение: моделът ще прочете ключовете много по-надеждно от свободен текст.

import json
from agents import function_tool

@function_tool
def get_sales_stats(month: str, year: int) -> str:
    """Retrieve sales statistics for a given month."""
    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

В допълнение към Вашите персонализирани функции, SDK предоставя достъп до инструменти, управлявани от OpenAI, които се изпълняват от страната на платформата.

from agents import Agent, WebSearchTool, FileSearchTool, CodeInterpreterTool

agent = Agent(
    name="General-purpose assistant",
    instructions="You are an assistant capable of searching the web, analyzing files, and executing code.",
    tools=[
        WebSearchTool(),
        FileSearchTool(
            vector_store_ids=["vs_abc123"],
            max_num_results=10,
        ),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

WebSearchTool позволява на агента да търси в интернет в реално време и не изисква конфигурация. FileSearchTool извършва семантично търсене във Вашите файлове, но предполага предварителна настройка: трябва да създадете векторно хранилище чрез OpenAI API и да качите документите си в него – оттук и vs_abc123, предаден като параметър. CodeInterpreterTool позволява на агента да пише и изпълнява Python код в изолиран контейнер, което го прави предпочитания избор за анализ на данни и генериране на графики. Изисква tool_config, който специфицира този контейнер: {"type": "auto"} го създава при поискване (SDK openai-agents отхвърля CodeInterpreterTool() без него).

Комбиниране на персонализирани и хоствани инструменти

Истинската сила се крие в комбинацията. На един финансов анализатор са му необходими Вашите вътрешни данни, възможности за изчисления и пазарен контекст: три източника, които нито един единствен инструмент не покрива.

agent = Agent(
    name="Financial analyst",
    instructions="""You are a financial analyst.
    Use internal tools to retrieve data,
    the code interpreter to analyze it,
    and web search for market context.""",
    tools=[
        get_sales_stats,
        search_customer,
        WebSearchTool(),
        CodeInterpreterTool(tool_config={"type": "code_interpreter", "container": {"type": "auto"}}),
    ],
)

Забележете как инструкциите уточняват за какво служи всяко семейство инструменти. Без тази яснота агент с четири инструмента ще се колебае, ще опита два ненужно и ще увеличи латентността без причина.

Ключови изводи

  • @function_tool превръща Python функция в инструмент за агент
  • Docstring-ът и type hints-овете автоматично генерират JSON схемата
  • Използвайте Pydantic за сложни параметри с валидация
  • Инструментите винаги връщат низове (JSON, ако са структурирани)
  • Комбинирайте Вашите персонализирани инструменти с WebSearchTool, FileSearchTool и CodeInterpreterTool