Δήλωση εργαλείων στο SDK
Σε αυτήν τη σελίδα
Δήλωση εργαλείων στο SDK
Τα εργαλεία αποτελούν τις συγκεκριμένες ικανότητες του πράκτορά σας. Χωρίς εργαλεία, ένας πράκτορας μπορεί μόνο να παράγει κείμενο· με εργαλεία, μπορεί να κάνει ερωτήματα σε βάσεις δεδομένων, να καλεί APIs και να στέλνει emails. Πρέπει όμως να τα δηλώνετε σωστά, επειδή η ποιότητα ενός εργαλείου δεν εξαρτάται μόνο από τον κώδικά του, αλλά και από το πόσο καλά το κατανοεί το μοντέλο.
Ο διακοσμητής @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 επικυρώνουν αυτόματα τις εισόδους και παρέχουν πλούσιες περιγραφές πεδίο προς πεδίο στο μοντέλο.
Επιστροφή δομημένων αποτελεσμάτων
Ένα εργαλείο επιστρέφει πάντα μια συμβολοσειρά (string). Όταν τα δεδομένα σας έχουν δομή—πολλαπλές μετρικές, μια λίστα, μικτοί τύποι—σειριοποιήστε τα ως 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 εκτελεί σημασιολογική αναζήτηση στα αρχεία σας, αλλά προϋποθέτει προηγούμενη ρύθμιση: πρέπει να δημιουργήσετε ένα vector store μέσω του OpenAI API και να ανεβάσετε τα έγγραφά σας σε αυτό· εξ ου και το vs_abc123 που περνάται ως παράμετρος. Το CodeInterpreterTool επιτρέπει στον πράκτορα να γράφει και να εκτελεί κώδικα Python σε ένα απομονωμένο container, καθιστώντας το την ιδανική επιλογή για ανάλυση δεδομένων και δημιουργία γραφημάτων. Απαιτεί ένα tool_config που καθορίζει αυτό το container: το {"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 και οι υποδείξεις τύπων δημιουργούν αυτόματα το σχήμα JSON
- Χρησιμοποιήστε το Pydantic για σύνθετες παραμέτρους με επικύρωση
- Τα εργαλεία επιστρέφουν πάντα συμβολοσειρές (JSON αν είναι δομημένες)
- Συνδυάστε τα προσαρμοσμένα εργαλεία σας με τα WebSearchTool, FileSearchTool και CodeInterpreterTool