Μετάβαση στο κύριο περιεχόμενο
Ελληνικά— Επιλέξτε γλώσσα
Μενού

Αρχιτεκτονική API Mistral Agents

Μάθημα 3 / 18 Ενημερώθηκε 3 Νοεμβρίου 2026 Για developers
Σε αυτήν τη σελίδα
  1. Τα Τρία Θεμελιώδη Αντικείμενα
  2. Το Αντικείμενο Agent
  3. Το Αντικείμενο Conversation
  4. Το Αντικείμενο Entry
  5. Σχέσεις Μεταξύ Αντικειμένων
  6. Επιλογές Συνομιλίας
  7. Βασικά σημεία

Ενημερώθηκε στις 3 Νοεμβρίου 2026. Το προηγούμενο πλήρες παράδειγμα agent περνούσε guardrails={"enabled": True}, μια μορφή που δεν υπάρχει: η επίσημη παράμετρος είναι μια λίστα διαμορφώσεων moderation_llm_v2. Η είσοδος tool.execution εκθέτει το όνομα του εργαλείου στο entry.name, όχι στο entry.tool_name, κάτι που προηγουμένως προκαλούσε AttributeError. Πηγές: Agents & Conversations · Moderation & Guardrailing · mistralai SDK 3.7.0.

Τα Τρία Θεμελιώδη Αντικείμενα

Το API Mistral Agents βασίζεται σε τρία αλληλεπιδρώντα αντικείμενα: Agent, Conversation και Entry. Τα περισσότερα σφάλματα σχεδιασμού που συναντώνται στην αρχή ενός έργου—όπως η επαναδημιουργία ενός agent για κάθε αίτημα, η επαναχρησιμοποίηση ενός ληγμένου conversation_id, ή η ανάλυση απόκρισης που καταρρέει σε μια απροσδόκητη εγγραφή—προέρχονται από σύγχυση μεταξύ αυτών των τριών επιπέδων. Η κατανόηση των ρόλων και των σχέσεών τους αποτελεί προαπαιτούμενο πριν γράψετε έστω και μία γραμμή κώδικα.

Το Αντικείμενο Agent

Ένα Agent είναι ένα σύνολο διαμορφώσεων που ορίζει τη συμπεριφορά του μοντέλου. Δεν περιέχει δεδομένα συνομιλίας: είναι ένα επαναχρησιμοποιήσιμο πρότυπο που δημιουργείτε μία φορά και στο οποίο μπορούν να αναφέρονται χιλιάδες συνομιλίες.

Η δημιουργία απαιτεί τουλάχιστον ένα μοντέλο, ένα όνομα και μια περιγραφή.

agent = client.beta.agents.create(
    model="mistral-large-latest",        # Μοντέλο LLM προς χρήση
    name="My Agent",                     # Αναγνώσιμο από άνθρωπο αναγνωριστικό
    description="Agent for financial analysis"  # Περιγραφή προσανατολισμένη στην εργασία
)

Η παράμετρος model ορίζει το μοντέλο που θα τροφοδοτήσει το agent, επιλεγμένο από τα διαθέσιμα μοντέλα ολοκλήρωσης συνομιλίας όπως το mistral-medium-latest ή το mistral-large-latest. Το name είναι ένα αναγνώσιμο από άνθρωπο αναγνωριστικό που χρησιμοποιείτε για να βρείτε και να αναφερθείτε στο agent: σε ένα έργο με είκοσι από αυτά, αυτό είναι που σας γλιτώνει από το να ψάχνετε στα αρχεία καταγραφής για να καταλάβετε ποιο απαντά στους πελάτες. Η description, από την άλλη πλευρά, είναι προσανατολισμένη στην εργασία και εξυπηρετεί κάτι περισσότερο από την εσωτερική τεκμηρίωση—βοηθά το μοντέλο να κατανοήσει τον ρόλο που αναμένεται από αυτό, γεγονός που εξηγεί τη διατύπωση “agent for financial analysis” αντί για ένα αόριστο “agent number 3”.

Τα υπόλοιπα διαμορφώνονται προαιρετικά, και εδώ είναι που διαμορφώνεται η πραγματική προσωπικότητα του agent.

agent = client.beta.agents.create(
    model="mistral-large-latest",
    name="Complete Agent",
    description="Agent with all parameters",
    instructions="You are a finance expert. Always respond with sources.",
    tools=[
        {"type": "web_search"},
        {"type": "code_interpreter"}
    ],
    completion_args={"temperature": 0.3, "top_p": 0.95},
    guardrails=[
        {
            "block_on_error": True,
            "moderation_llm_v2": {
                "custom_category_thresholds": {"jailbreaking": 0.2, "financial": 1},
                "action": "block",
            },
        }
    ],
)
  • instructions — Η προτροπή συστήματος του agent (ορίζει την προσωπικότητα, τους κανόνες και το στυλ του)
  • tools — Λίστα διαθέσιμων εργαλείων: web_search, web_search_premium, code_interpreter, image_generation, document_library, ή προσαρμοσμένες συναρτήσεις
  • completion_args — Παράμετροι δειγματοληψίας (temperature, top_p, max_tokens, κ.λπ.)
  • guardrails — Μια λίστα διαμορφώσεων moderation (moderation_llm_v2) που εφαρμόζονται στο εισερχόμενο μήνυμα κάθε συνομιλίας του agent· εδώ, το jailbreaking αποκλείεται πάνω από 0.2 και η κατηγορία financial απενεργοποιείται (κατώφλι 1), καθώς το agent έχει κατασκευαστεί για να συζητά οικονομικά θέματα. Οι λεπτομέρειες βρίσκονται στο μάθημα AI Moderation and Security with Mistral.

Στο παραπάνω παράδειγμα, το οικονομικό agent κληρονομεί μια απαίτηση για πηγές από τις οδηγίες του, την ικανότητα επαλήθευσης ενός αριθμού από τα εργαλεία του, και μια χαμηλή θερμοκρασία που περιορίζει τη δημιουργικότητα εκεί που αναμένεται αυστηρότητα.

Το Αντικείμενο Conversation

Μια Conversation είναι το ιστορικό αλληλεπιδράσεων μεταξύ ενός χρήστη και ενός agent—ή μεταξύ ενός χρήστη και ενός μοντέλου μόνο του. Περιέχει μηνύματα, αποτελέσματα εκτέλεσης εργαλείων και γεγονότα μεταβίβασης (handoff).

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Analyze trends in the European AI market."
)

# Ανακτήστε το ID συνομιλίας για συνέχεια αργότερα
conversation_id = response.conversation_id

Η συμπεριφορά αυτού του αντικειμένου κρύβει μερικές εκπλήξεις. Η συνομιλία είναι επίμονη: το ιστορικό αποθηκεύεται στην πλευρά της Mistral, εκτός αν περάσετε store=False. Είναι ανεξάρτητη από το agent, που σημαίνει ότι μια συνομιλία μπορεί κάλλιστα να υπάρχει χωρίς agent, σε λειτουργία άμεσου μοντέλου. Τέλος, είναι αμετάβλητη: κάθε προσθήκη επιστρέφει ένα νέο conversation_id, με το παλιό να παραμένει προσβάσιμο. Αυτό το τελευταίο σημείο είναι το πιο εκπληκτικό: αν αποθηκεύσετε το αρχικό ID στη βάση δεδομένων σας και το επαναχρησιμοποιήσετε στον τρίτο γύρο, θα επιστρέψετε στο πλαίσιο της πρώτης ανταλλαγής.

Το Αντικείμενο Entry

Ένα Entry είναι μια μεμονωμένη ενέργεια μέσα σε μια συνομιλία: η ατομική μονάδα του ιστορικού. Όταν λαμβάνετε μια απόκριση, το πεδίο outputs περιέχει μια λίστα εγγραφών των οποίων ο τύπος εξαρτάται από το τι έκανε το agent. Μια εγγραφή message.output μεταφέρει μια κειμενική απόκριση από το agent, δηλαδή το κείμενο που θα εμφανίσει η διεπαφή σας. Μια εγγραφή tool.execution μεταφέρει το αποτέλεσμα εκτέλεσης ενός εργαλείου, όπως κώδικας ή μια αναζήτηση στον ιστό: το σενάριο που εκκινήθηκε και την έξοδό του, ή τις σελίδες που επέστρεψε η μηχανή. Μια εγγραφή agent.handoff σηματοδοτεί ένα γεγονός μεταβίβασης σε άλλο agent, και επομένως εμφανίζεται μόνο σε σενάρια πολλαπλών agents.

Μια μοναδική απόκριση συχνά αναμειγνύει αυτούς τους τύπους. Ζητήστε από ένα agent με εργαλεία έναν υπολογισμό και θα λάβετε την εκτέλεση, και στη συνέχεια τον σχολιασμό που τη συνοδεύει: ο κώδικάς σας πρέπει επομένως να επαναλάβει αυτή τη λίστα αντί να διαβάσει ένα μόνο πεδίο.

response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Calculate the square root of 144"
)

for entry in response.outputs:
    print(f"Type: {entry.type}")
    if entry.type == "message.output":
        print(f"Message: {entry.content}")
    elif entry.type == "tool.execution":
        print(f"Tool: {entry.name}")

Σχέσεις Μεταξύ Αντικειμένων

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

Agent (configuration)
  ├── model, instructions, tools, guardrails
  └── Can be referenced by N conversations

Conversation (history)
  ├── Linked to 0 or 1 Agent (optional)
  ├── Contains N ordered entries
  └── Each append creates a new conversation_id

Entry (unit action)
  ├── message.output (text response)
  ├── tool.execution (tool result)
  └── agent.handoff (agent transfer)

Επιλογές Συνομιλίας

Η έναρξη μιας συνομιλίας δέχεται ρυθμίσεις που επηρεάζουν τόσο τη συμμόρφωσή σας όσο και την αρχιτεκτονική σας, και είναι καλύτερα να τις αποφασίζετε εσείς παρά να τις υφίσταστε. Πρώτα η αποθήκευση: το store=False αποτρέπει οποιαδήποτε αποθήκευση στην πλευρά της Mistral, κάτι που θα χρησιμοποιήσετε για την επεξεργασία δεδομένων που η εσωτερική σας πολιτική απαγορεύει να φύγουν από έναν διακομιστή τρίτου μέρους.

# Απενεργοποίηση αποθήκευσης στο cloud
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Sensitive question",
    store=False
)

Η δεύτερη ρύθμιση ορίζει ποιος εκτελεί τις μεταβιβάσεις (handoffs). Στη λειτουργία server, την προεπιλεγμένη τιμή, η Mistral αλυσιδώνει τις μεταβιβάσεις agents χωρίς την παρέμβασή σας· στη λειτουργία client, λαμβάνετε γεγονότα handoff και διατηρείτε τον έλεγχο για να καταγράψετε, να φιλτράρετε ή να απορρίψετε αυτά τα γεγονότα.

# Λειτουργία Server (προεπιλογή) — Η Mistral χειρίζεται αυτόματα τα handoffs
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="server"
)

# Λειτουργία Client — Λαμβάνετε γεγονότα handoff και αποφασίζετε τι να κάνετε
response = client.beta.conversations.start(
    agent_id=agent.id,
    inputs="Complex request",
    handoff_execution="client"
)

Βασικά σημεία

  • Agent = επαναχρησιμοποιήσιμη διαμόρφωση (μοντέλο, οδηγίες, εργαλεία, guardrails)
  • Conversation = επίμονο ιστορικό αποθηκευμένο στον διακομιστή, ανεξάρτητο από το agent
  • Entry = μοναδιαία ενέργεια (μήνυμα, εκτέλεση εργαλείου, handoff)
  • Οι συνομιλίες μπορούν να υπάρχουν χωρίς agent (λειτουργία άμεσου μοντέλου)
  • Κάθε προσθήκη σε μια συνομιλία δημιουργεί ένα νέο conversation_id
  • Η λειτουργία store=False αποτρέπει την αποθήκευση στην πλευρά της Mistral