ai-agents-for-beginners

Πώς να Σχεδιάσετε Καλούς Πράκτορες Τεχνητής Νοημοσύνης

(Κάντε κλικ στην εικόνα παραπάνω για να δείτε το βίντεο αυτής της μαθήματος)

Πρότυπο Σχεδίασης Χρήσης Εργαλείων

Τα εργαλεία είναι ενδιαφέροντα επειδή επιτρέπουν στους πράκτορες AI να έχουν ευρύτερο φάσμα δυνατοτήτων. Αντί να έχει ο πράκτορας ένα περιορισμένο σύνολο ενεργειών που μπορεί να εκτελέσει, με την προσθήκη ενός εργαλείου, μπορεί πλέον να εκτελέσει ένα ευρύ φάσμα ενεργειών. Σε αυτό το κεφάλαιο, θα εξετάσουμε το Πρότυπο Σχεδίασης Χρήσης Εργαλείων, που περιγράφει πώς οι πράκτορες AI μπορούν να χρησιμοποιούν συγκεκριμένα εργαλεία για να πετύχουν τους στόχους τους.

Εισαγωγή

Σε αυτό το μάθημα, επιδιώκουμε να απαντήσουμε στις ακόλουθες ερωτήσεις:

Στόχοι Μάθησης

Μετά την ολοκλήρωση αυτού του μαθήματος, θα μπορείτε να:

Τι είναι το Πρότυπο Σχεδίασης Χρήσης Εργαλείων;

Το Πρότυπο Σχεδίασης Χρήσης Εργαλείων εστιάζει στο να δώσει στα LLMs τη δυνατότητα να αλληλεπιδρούν με εξωτερικά εργαλεία για να επιτύχουν συγκεκριμένους στόχους. Τα εργαλεία είναι κώδικας που μπορεί να εκτελεστεί από έναν πράκτορα για να εκτελέσει ενέργειες. Ένα εργαλείο μπορεί να είναι μια απλή συνάρτηση όπως ένας υπολογιστής ή μια κλήση API σε υπηρεσία τρίτου, όπως η αναζήτηση τιμής μετοχής ή πρόβλεψη καιρού. Στο πλαίσιο των πρακτόρων AI, τα εργαλεία σχεδιάζονται να εκτελούνται από πράκτορες ως απάντηση σε κλήσεις συνάρτησης που παράγονται από το μοντέλο.

Σε ποιες περιπτώσεις χρήσης μπορεί να εφαρμοστεί;

Οι πράκτορες AI μπορούν να αξιοποιήσουν εργαλεία για να ολοκληρώσουν σύνθετα καθήκοντα, να ανακτήσουν πληροφορίες ή να λάβουν αποφάσεις. Το πρότυπο σχεδίασης χρήσης εργαλείων χρησιμοποιείται συχνά σε σενάρια που απαιτούν δυναμική αλληλεπίδραση με εξωτερικά συστήματα, όπως βάσεις δεδομένων, υπηρεσίες διαδικτύου ή διερμηνείς κώδικα. Αυτή η δυνατότητα είναι χρήσιμη για διάφορες περιπτώσεις χρήσης, όπως:

Ποια είναι τα στοιχεία/δομικά μπλοκ που χρειάζονται για την υλοποίηση του προτύπου σχεδίασης χρήσης εργαλείων;

Αυτά τα δομικά μπλοκ επιτρέπουν στον πράκτορα AI να εκτελεί ένα ευρύ φάσμα εργασιών. Ας δούμε τα βασικά στοιχεία που απαιτούνται για την υλοποίηση του Προτύπου Σχεδίασης Χρήσης Εργαλείων:

Στη συνέχεια, ας δούμε πιο αναλυτικά την Κλήση Συνάρτησης/Εργαλείου.

Κλήση Συνάρτησης/Εργαλείου

Η κλήση συνάρτησης είναι ο κύριος τρόπος με τον οποίο επιτρέπουμε στα Μεγάλα Μοντέλα Γλώσσας (LLMs) να αλληλεπιδρούν με εργαλεία. Συχνά θα δείτε τους όρους ‘Συνάρτηση’ και ‘Εργαλείο’ να χρησιμοποιούνται εναλλακτικά επειδή οι ‘συναρτήσεις’ (μπλοκ επαναχρησιμοποιήσιμου κώδικα) είναι τα ‘εργαλεία’ που χρησιμοποιούν οι πράκτορες για να εκτελούν εργασίες. Για να κληθεί ο κώδικας μιας συνάρτησης, ένα LLM πρέπει να συγκρίνει το αίτημα των χρηστών με την περιγραφή της συνάρτησης. Για να γίνει αυτό, ένα σχήμα που περιέχει τις περιγραφές όλων των διαθέσιμων συναρτήσεων αποστέλλεται στο LLM. Στη συνέχεια, το LLM επιλέγει την πιο κατάλληλη συνάρτηση για την εργασία και επιστρέφει το όνομα και τα επιχειρήματα της. Η επιλεγμένη συνάρτηση καλείται, η απάντησή της αποστέλλεται πίσω στο LLM, το οποίο χρησιμοποιεί την πληροφορία για να ανταποκριθεί στο αίτημα των χρηστών.

Για να υλοποιήσουν οι προγραμματιστές κλήση συνάρτησης για πράκτορες, θα χρειαστείτε:

  1. Ένα μοντέλο LLM που υποστηρίζει κλήση συνάρτησης
  2. Ένα σχήμα που περιέχει περιγραφές συναρτήσεων
  3. Τον κώδικα για κάθε περιγραφόμενη συνάρτηση

Ας χρησιμοποιήσουμε το παράδειγμα λήψης της τρέχουσας ώρας σε μια πόλη για να το απεικονίσουμε:

  1. Αρχικοποίηση ενός LLM που υποστηρίζει κλήση συνάρτησης:

    Δεν υποστηρίζουν όλα τα μοντέλα την κλήση συνάρτησης, οπότε είναι σημαντικό να ελέγξετε ότι το LLM που χρησιμοποιείτε το υποστηρίζει. Το Azure OpenAI υποστηρίζει κλήση συνάρτησης. Μπορούμε να ξεκινήσουμε δημιουργώντας έναν OpenAI client για το Azure OpenAI Responses API (το σταθερό endpoint /openai/v1/ — δεν χρειάζεται api_version).

     # Αρχικοποιήστε τον πελάτη OpenAI για το Azure OpenAI (API Απαντήσεων, τελικό σημείο v1)
 client = OpenAI(
     base_url=f"{os.environ['AZURE_OPENAI_ENDPOINT'].rstrip('/')}/openai/v1/",
     api_key=os.environ["AZURE_OPENAI_API_KEY"],
 )
 deployment_name = os.environ["AZURE_OPENAI_DEPLOYMENT"]

  2. Δημιουργία Σχήματος Συνάρτησης:

    Στη συνέχεια, θα ορίσουμε ένα σχήμα JSON που περιέχει το όνομα της συνάρτησης, περιγραφή του τι κάνει η συνάρτηση, και τα ονόματα και περιγραφές των παραμέτρων της συνάρτησης. Μετά θα περάσουμε αυτό το σχήμα στον πελάτη που δημιουργήσαμε προηγουμένως, μαζί με το αίτημα του χρήστη να βρει την ώρα στο Σαν Φρανσίσκο. Το σημαντικό να σημειωθεί είναι ότι επιστρέφεται μια κλήση εργαλείου, όχι η τελική απάντηση στην ερώτηση. Όπως αναφέρθηκε νωρίτερα, το LLM επιστρέφει το όνομα της συνάρτησης που επέλεξε για την εργασία και τα επιχειρήματα που θα της περαστούν.

     # Περιγραφή λειτουργίας για το μοντέλο να διαβάσει (μορφή εργαλείου API απαντήσεων flat)
 tools = [
     {
         "type": "function",
         "name": "get_current_time",
         "description": "Get the current time in a given location",
         "parameters": {
             "type": "object",
             "properties": {
                 "location": {
                     "type": "string",
                     "description": "The city name, e.g. San Francisco",
                 },
             },
             "required": ["location"],
         },
     }
 ]

      
 # Αρχικό μήνυμα χρήστη
 messages = [{"role": "user", "content": "What's the current time in San Francisco"}]

 # Πρώτη κλήση API: Ζητήστε από το μοντέλο να χρησιμοποιήσει τη λειτουργία
 response = client.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     tool_choice="auto",
     store=False,
 )

 # Το Responses API επιστρέφει κλήσεις εργαλείων ως στοιχεία function_call στο response.output.
 # Προσθέστε τα στη συνομιλία ώστε το μοντέλο να έχει πλήρες πλαίσιο στην επόμενη ανταλλαγή.
 messages += response.output

 print("Model's response:")
 print(response.output)
  

     Model's response:
 [ResponseFunctionToolCall(arguments='{"location":"San Francisco"}', call_id='call_pOsKdUlqvdyttYB67MOj434b', name='get_current_time', type='function_call')]

  3. Ο κώδικας της συνάρτησης που απαιτείται για την εκτέλεση της εργασίας:

    Τώρα που το LLM έχει επιλέξει ποια συνάρτηση πρέπει να τρέξει, ο κώδικας που εκτελεί την εργασία πρέπει να υλοποιηθεί και να εκτελεστεί. Μπορούμε να υλοποιήσουμε τον κώδικα για να πάρουμε την τρέχουσα ώρα σε Python. Θα χρειαστεί επίσης να γράψουμε κώδικα για να εξάγουμε το όνομα και τα επιχειρήματα από το response_message για να πάρουμε το τελικό αποτέλεσμα.

       def get_current_time(location):
     """Get the current time for a given location"""
     print(f"get_current_time called with location: {location}")  
     location_lower = location.lower()
        
     for key, timezone in TIMEZONE_DATA.items():
         if key in location_lower:
             print(f"Timezone found for {key}")  
             current_time = datetime.now(ZoneInfo(timezone)).strftime("%I:%M %p")
             return json.dumps({
                 "location": location,
                 "current_time": current_time
             })
      
     print(f"No timezone data found for {location_lower}")  
     return json.dumps({"location": location, "current_time": "unknown"})

     # Διαχείριση κλήσεων συναρτήσεων
 tool_calls = [item for item in response.output if item.type == "function_call"]
 if tool_calls:
     for tool_call in tool_calls:
         if tool_call.name == "get_current_time":

             function_args = json.loads(tool_call.arguments)

             time_response = get_current_time(
                 location=function_args.get("location")
             )

             # Επιστροφή του αποτελέσματος του εργαλείου ως στοιχείο function_call_output
             messages.append({
                 "type": "function_call_output",
                 "call_id": tool_call.call_id,
                 "output": time_response,
             })
 else:
     print("No tool calls were made by the model.")

 # Δεύτερη κλήση API: Λήψη της τελικής απάντησης από το μοντέλο
 final_response = client.responses.create(
     model=deployment_name,
     input=messages,
     tools=tools,
     store=False,
 )

 return final_response.output_text

       get_current_time called with location: San Francisco
   Timezone found for san francisco
   The current time in San Francisco is 09:24 AM.

Η Κλήση Συνάρτησης είναι στον πυρήνα των περισσότερων, αν όχι όλων, σχεδίων χρήσης εργαλείων από πράκτορες, ωστόσο η υλοποίησή της από το μηδέν μπορεί να είναι μερικές φορές απαιτητική. Όπως μάθαμε στο Μάθημα 2, τα agentic frameworks μας παρέχουν προκατασκευασμένα δομικά μπλοκ για να υλοποιήσουμε τη χρήση εργαλείων.

Παραδείγματα Χρήσης Εργαλείων με Agentic Frameworks

Εδώ είναι μερικά παραδείγματα για το πώς μπορείτε να υλοποιήσετε το Πρότυπο Σχεδίασης Χρήσης Εργαλείων χρησιμοποιώντας διαφορετικά agentic frameworks:

Microsoft Agent Framework

Το Microsoft Agent Framework είναι ένα ανοιχτού κώδικα πλαίσιο AI για την κατασκευή πρακτόρων AI. Απλοποιεί τη διαδικασία χρήσης κλήσης συνάρτησης επιτρέποντάς σας να ορίζετε εργαλεία ως συναρτήσεις Python με τον διακοσμητή @tool. Το πλαίσιο διαχειρίζεται την αμφίδρομη επικοινωνία μεταξύ του μοντέλου και του κώδικά σας. Παρέχει επίσης πρόσβαση σε προκατασκευασμένα εργαλεία όπως Αναζήτηση Αρχείων και Διερμηνέα Κώδικα μέσω του FoundryChatClient.

Το παρακάτω διάγραμμα απεικονίζει τη διαδικασία κλήσης συνάρτησης με το Microsoft Agent Framework:

function calling

Στο Microsoft Agent Framework, τα εργαλεία ορίζονται ως διακοσμημένες συναρτήσεις. Μπορούμε να μετατρέψουμε τη συνάρτηση get_current_time που είδαμε προηγουμένως σε εργαλείο χρησιμοποιώντας τον διακοσμητή @tool. Το πλαίσιο θα σειριοποιήσει αυτόματα τη συνάρτηση και τις παραμέτρους της, δημιουργώντας το σχήμα που θα σταλεί στο LLM.

import os
from agent_framework import tool
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

@tool(approval_mode="never_require")
def get_current_time(location: str) -> str:
    """Get the current time for a given location"""
    ...

# Δημιουργήστε τον πελάτη
provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)

# Δημιουργήστε έναν πράκτορα και εκτελέστε με το εργαλείο
agent = provider.as_agent(name="TimeAgent", instructions="Use available tools to answer questions.", tools=get_current_time)
response = await agent.run("What time is it?")

Microsoft Foundry Agent Service

Η Υπηρεσία Πρακτόρων Microsoft Foundry είναι ένα νεότερο agentic framework που έχει σχεδιαστεί για να δίνει στους προγραμματιστές τη δυνατότητα να δημιουργούν, να αναπτύσσουν και να κλιμακώνουν με ασφάλεια υψηλής ποιότητας επεκτάσιμους πράκτορες AI χωρίς να χρειάζεται να διαχειρίζονται τους υποκείμενους πόρους υπολογισμού και αποθήκευσης. Είναι ιδιαίτερα χρήσιμο για επιχειρησιακές εφαρμογές καθώς είναι μια πλήρως διαχειριζόμενη υπηρεσία με ασφάλεια επιπέδου επιχείρησης.

Σε σύγκριση με την απευθείας ανάπτυξη με το LLM API, η Υπηρεσία Πρακτόρων Microsoft Foundry παρέχει μερικά πλεονεκτήματα, όπως:

Τα εργαλεία που είναι διαθέσιμα στην Υπηρεσία Πρακτόρων Microsoft Foundry μπορούν να χωριστούν σε δύο κατηγορίες:

  1. Εργαλεία Γνώσης:
  2. Εργαλεία Δράσης:

Η Υπηρεσία Πρακτόρων μας επιτρέπει να χρησιμοποιούμε αυτά τα εργαλεία μαζί ως toolset. Χρησιμοποιεί επίσης νήματα που παρακολουθούν το ιστορικό μηνυμάτων μιας συγκεκριμένης συνομιλίας.

Φανταστείτε ότι είστε ένας πωλητής σε μια εταιρεία που ονομάζεται Contoso. Θέλετε να αναπτύξετε έναν συνομιλητικό πράκτορα που μπορεί να απαντήσει σε ερωτήματα σχετικά με τα στοιχεία πωλήσεών σας.

Η παρακάτω εικόνα απεικονίζει πώς θα μπορούσατε να χρησιμοποιήσετε την Υπηρεσία Πρακτόρων Microsoft Foundry για να αναλύσετε τα δεδομένα πωλήσεών σας:

Agentic Service In Action

Για να χρησιμοποιήσουμε οποιοδήποτε από αυτά τα εργαλεία με την υπηρεσία, μπορούμε να δημιουργήσουμε έναν πελάτη και να ορίσουμε ένα εργαλείο ή σύνολο εργαλείων. Για να το υλοποιήσουμε πρακτικά, μπορούμε να χρησιμοποιήσουμε τον ακόλουθο κώδικα Python. Το LLM θα μπορεί να κοιτάξει το σύνολο εργαλείων και να αποφασίσει αν θα χρησιμοποιήσει τη συνάρτηση που δημιούργησε ο χρήστης, fetch_sales_data_using_sqlite_query, ή τον προκατασκευασμένο Διερμηνέα Κώδικα, ανάλογα με το αίτημα του χρήστη.

import os
from azure.ai.projects import AIProjectClient
from azure.identity import DefaultAzureCredential
from fetch_sales_data_functions import fetch_sales_data_using_sqlite_query # συνάρτηση fetch_sales_data_using_sqlite_query που μπορεί να βρεθεί σε ένα αρχείο fetch_sales_data_functions.py.
from azure.ai.projects.models import ToolSet, FunctionTool, CodeInterpreterTool

project_client = AIProjectClient.from_connection_string(
    credential=DefaultAzureCredential(),
    conn_str=os.environ["PROJECT_CONNECTION_STRING"],
)

# Αρχικοποίηση σετ εργαλείων
toolset = ToolSet()

# Αρχικοποίηση πράκτορα κλήσης συναρτήσεων με τη συνάρτηση fetch_sales_data_using_sqlite_query και προσθήκη της στο σετ εργαλείων
fetch_data_function = FunctionTool(fetch_sales_data_using_sqlite_query)
toolset.add(fetch_data_function)

# Αρχικοποίηση εργαλείου διερμηνέα κώδικα και προσθήκη του στο σετ εργαλείων.
code_interpreter = CodeInterpreterTool()toolset.add(code_interpreter)

agent = project_client.agents.create_agent(
    model="gpt-5-mini", name="my-agent", instructions="You are helpful agent", 
    toolset=toolset
)

Ποιες είναι οι ειδικές προϋποθέσεις για τη χρήση του Προτύπου Σχεδίασης Χρήσης Εργαλείων για την κατασκευή αξιόπιστων πρακτόρων AI;

Ένα κοινό ζήτημα με τη δυναμική SQL που δημιουργείται από LLMs είναι η ασφάλεια, ιδιαίτερα ο κίνδυνος SQL injection ή κακόβουλων ενεργειών, όπως η διαγραφή ή παραποίηση της βάσης δεδομένων. Παρόλο που αυτοί οι προβληματισμοί είναι έγκυροι, μπορούν να αντιμετωπιστούν αποτελεσματικά με σωστό καθορισμό των δικαιωμάτων πρόσβασης στη βάση δεδομένων. Για τις περισσότερες βάσεις δεδομένων αυτό σημαίνει ρύθμιση της βάσης σε κατάσταση μόνο για ανάγνωση. Για υπηρεσίες βάσεων δεδομένων όπως PostgreSQL ή Azure SQL, η εφαρμογή πρέπει να ανατεθεί σε ρόλο μόνο για ανάγνωση (SELECT).

Η εκτέλεση της εφαρμογής σε ασφαλές περιβάλλον αυξάνει περαιτέρω την προστασία. Σε επιχειρησιακά σενάρια, δεδομένα συνήθως εξαχθούν και μετασχηματίζονται από λειτουργικά συστήματα σε βάση δεδομένων ή data warehouse μόνο για ανάγνωση με φιλικό προς το χρήστη σχήμα. Αυτή η προσέγγιση εξασφαλίζει ότι τα δεδομένα είναι ασφαλή, βελτιστοποιημένα για απόδοση και προσβασιμότητα, και ότι η εφαρμογή έχει περιορισμένη, μόνο για ανάγνωση πρόσβαση.

Παραδείγματα Κώδικα

Έχετε Περισσότερες Ερωτήσεις σχετικά με τα Πρότυπα Σχεδίασης Χρήσης Εργαλείων;

Ενώστε το Microsoft Foundry Discord για να συναντήσετε άλλους μαθητές, να παρακολουθήσετε ώρες γραφείου και να λάβετε απαντήσεις στις ερωτήσεις σας για πράκτορες AI.

Πρόσθετοι Πόροι

Έλεγχος Καπνού αυτού του Πράκτορα (Προαιρετικό)

Αφού μάθετε πώς να αναπτύσσετε πράκτορες στο Μάθημα 16, μπορείτε να κάνετε έναν έλεγχο καπνού στον TravelToolAgent αυτού του μαθήματος (καλείται ακόμα τα εργαλεία του και απαντά;) με το tests/lesson-04-smoke-tests.json. Δείτε το tests/README.md για το πώς να το τρέξετε.

Προηγούμενο Μάθημα

Κατανόηση των Ραγών Σχεδίασης Πρακτόρων

Επόμενο Μάθημα

Agentic RAG

Αποποίηση ευθυνών: Αυτό το έγγραφο έχει μεταφραστεί χρησιμοποιώντας την υπηρεσία μετάφρασης με τεχνητή νοημοσύνη Co-op Translator. Ενώ επιδιώκουμε την ακρίβεια, παρακαλούμε να έχετε υπόψη ότι οι αυτοματοποιημένες μεταφράσεις ενδέχεται να περιέχουν λάθη ή ανακρίβειες. Το πρωτότυπο έγγραφο στη μητρική του γλώσσα πρέπει να θεωρείται η αυθεντική πηγή. Για κρίσιμες πληροφορίες, συνιστάται επαγγελματική ανθρώπινη μετάφραση. Δεν φέρουμε ευθύνη για τυχόν παρεξηγήσεις ή λανθασμένες ερμηνείες που προκύπτουν από τη χρήση αυτής της μετάφρασης.

This site is open source. Improve this page.