8 Εκτέλεση agent μέσω API
8.1 Πώς λειτουργεί το API εκτέλεσης agents
Χρησιμοποιήστε το API εκτέλεσης agents για να εκτελέσετε έναν από τους agents του Χώρου εργασίας, όπως το Knowledge Search, το Deep Research ή το Presentation, από δικό σας πρόγραμμα ή εφαρμογή, χωρίς συνομιλία. Κάθε αίτημα ξεκινά μία εκτέλεση. Στη συνέχεια ο πελάτης σας ελέγχει την εκτέλεση μέχρι να ολοκληρωθεί και διαβάζει την απάντηση και τυχόν αρχεία.
Κάθε εκτέλεση είναι αυτοτελής. Δεν έχει ιστορικό συνομιλίας και ο agent δεν μπορεί να σας κάνει συμπληρωματική ερώτηση. Για να εκτελέσετε έναν agent μέσα σε συνομιλία, χρησιμοποιήστε το API συνομιλίας. Για να στείλετε ένα αίτημα και να αφήσετε το Sophea να επιλέξει τους agents και τα εργαλεία, δείτε Αφήστε το Sophea να επιλέξει τους agents.
8.2 Αποκτήστε διακριτικό
Χρησιμοποιήστε προσωπικό διακριτικό ή διακριτικό λογαριασμού υπηρεσίας, όπως περιγράφεται στην ενότητα Αποκτήστε διακριτικό και διεύθυνση Χώρου εργασίας, και στείλτε το στην κεφαλίδα Authorization: Bearer κάθε αιτήματος. Το διακριτικό ενεργεί ως ο κάτοχός του: μια εκτέλεση φτάνει μόνο στα έγγραφα και στους agents που μπορεί να χρησιμοποιήσει ο κάτοχος.
NOUS_URL='https://nous.sophea.ai'
NOUS_TOKEN='<paste-your-token>'8.3 Δείτε τους agents
curl -sS "$NOUS_URL/api/external-agents" \
-H "Authorization: Bearer $NOUS_TOKEN"Η απόκριση περιέχει κάθε agent που έχει προστεθεί στον Χώρο εργασίας. Κάθε στοιχείο περιλαμβάνει:
| Πεδίο | Σημασία |
|---|---|
slug |
Το όνομα που χρησιμοποιείτε στη διεύθυνση της εκτέλεσης, για παράδειγμα nous-rag ή research. |
display_name |
Το όνομα του agent στο Nous. |
description |
Τι κάνει ο agent. Χρησιμοποιήστε το για να επιλέξετε agent. |
tags |
Σύντομες ετικέτες του agent. |
unavailable |
true όταν ο Χώρος εργασίας δεν μπορεί να εκτελέσει αυτόν τον agent αυτή τη στιγμή. |
8.4 Ξεκινήστε μια εκτέλεση
Επιλέξτε ένα ID λειτουργίας για την εκτέλεση: 1 έως 64 γράμματα, ψηφία, _ ή -. Έπειτα στείλτε το κείμενο του αιτήματος με PUT:
curl -sS -X PUT "$NOUS_URL/api/external-agents/research/operations/q3-market-2026" \
-H "Authorization: Bearer $NOUS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"prompt": "Τι άλλαξε στο πλάνο πωλήσεων του τρίτου τριμήνου και πώς συγκρίνεται με την αγορά;"}'Το σώμα περιέχει μόνο το prompt. Το prompt μπορεί να έχει έως 50.000 χαρακτήρες, ή 4.000 για το Knowledge Search (nous-rag).
Η επανάληψη του ίδιου PUT μέσα σε 24 ώρες είναι ασφαλής: επιστρέφει την ίδια εκτέλεση αντί να ξεκινήσει δεύτερη. Μια εκτέλεση διατηρείται για 24 ώρες από την τελευταία της αλλαγή· μετά από αυτό, το ίδιο αίτημα ξεκινά νέα εκτέλεση. Αν στείλετε διαφορετικό prompt με ID λειτουργίας που έχετε ήδη χρησιμοποιήσει, επιστρέφεται HTTP 409. Το ίδιο prompt μπορεί επίσης να επιστρέψει 409 όταν η πρόσβαση του κατόχου του διακριτικού σε έγγραφα άλλαξε μετά την έναρξη της εκτέλεσης, για παράδειγμα μετά από νέο ανέβασμα αρχείου· το GET εξακολουθεί να επιστρέφει την εκτέλεση. Χρησιμοποιήστε νέο ID λειτουργίας για κάθε νέο αίτημα.
Κάθε άτομο μπορεί να έχει δέκα εκτελέσεις με επιλεγμένο agent σε εξέλιξη ταυτόχρονα. Ένα PUT που θα ξεκινούσε ενδέκατη επιστρέφει HTTP 429 με κεφαλίδα Retry-After που λέει πόσα δευτερόλεπτα να περιμένετε· μετά από αυτά στείλτε ξανά το ίδιο PUT. Η επανάληψη του PUT μιας εκτέλεσης που υπάρχει ήδη δεν απορρίπτεται ποτέ.
8.5 Ελέγξτε την εκτέλεση και διαβάστε την απάντηση
Διαβάστε την εκτέλεση με GET στην ίδια διεύθυνση:
curl -sS "$NOUS_URL/api/external-agents/research/operations/q3-market-2026" \
-H "Authorization: Bearer $NOUS_TOKEN"Το PUT και το GET επιστρέφουν τα ίδια πεδία:
| Πεδίο | Σημασία |
|---|---|
status |
pending ή running όσο εργάζεται ο agent· completed, failed ή cancelled όταν η εκτέλεση έχει ολοκληρωθεί. |
final_text |
Η απάντηση του agent, μόλις ολοκληρωθεί η εκτέλεση· null όσο εκτελείται. |
artifacts |
Τα αρχεία που δημιούργησε ο agent, μόλις ολοκληρωθεί η εκτέλεση. |
sources |
Οι πηγές που παραθέτει η απάντηση, μόλις ολοκληρωθεί η εκτέλεση. Το n είναι ο αριθμός που χρησιμοποιεί η απάντηση, όπως [1]· το kind είναι web, document (έγγραφο του Χώρου εργασίας) ή record (εγγραφή από τη δική του συλλογή ενός agent, όπως ένας νόμος ή ένας διαγωνισμός)· τα title και url ονομάζουν την πηγή· ένα έγγραφο του Χώρου εργασίας έχει επίσης το source_type του, όπως file. |
notice |
Ένα code και params που εξηγούν ένα όριο που συνάντησε η εκτέλεση, όπως εξαντλημένα credits του Χώρου εργασίας, ή null. |
created_at, updated_at, completed_at |
Πότε ξεκίνησε, πότε άλλαξε τελευταία φορά και πότε ολοκληρώθηκε η εκτέλεση. |
Όσο η εκτέλεση δεν έχει ολοκληρωθεί, ελέγχετε ξανά κάθε λίγα δευτερόλεπτα. Το Deep Research χρειάζεται μερικά λεπτά. Στείλτε επίσης το ίδιο PUT περίπου κάθε 30 δευτερόλεπτα: αν σταμάτησε η διεργασία που εκτελεί τον agent, η εκτέλεση ξεκινά ξανά.
8.6 Κατεβάστε αρχεία
Κάθε στοιχείο του artifacts έχει artifact_id και download_url και, όταν είναι γνωστά, filename, content_type, size_bytes και sha256. Κατεβάστε ένα αρχείο με το ίδιο διακριτικό:
curl -sS -o slides.pptx "$NOUS_URL<download_url>" \
-H "Authorization: Bearer $NOUS_TOKEN"Το GET .../operations/<operation_id>/artifacts επιστρέφει ξανά τη λίστα των αρχείων. Ένα αρχείο για λήψη μπορεί να έχει έως 100 MiB.
8.7 Ακυρώστε μια εκτέλεση
curl -sS -X DELETE "$NOUS_URL/api/external-agents/research/operations/q3-market-2026" \
-H "Authorization: Bearer $NOUS_TOKEN"Η εκτέλεση τελειώνει με κατάσταση cancelled. Η ακύρωση μιας εκτέλεσης που έχει ήδη ολοκληρωθεί δεν αλλάζει τίποτα.
8.8 Πάρτε τα πάντα σε μία απάντηση
Ο agent δεν μπορεί να σας κάνει ερώτηση κατά την εκτέλεση μέσω API. Όταν χρειάζεται περισσότερες πληροφορίες, για παράδειγμα ποιο γράφημα να μπει σε μια παρουσίαση, η τελική του απάντηση λέει τι λείπει. Στείλτε νέα εκτέλεση με νέο ID λειτουργίας και συμπεριλάβετε τα πάντα στο prompt.
Το Knowledge Search και το Deep Research αναζητούν στα έγγραφα του Χώρου εργασίας που μπορεί να διαβάσει ο κάτοχος του διακριτικού, μαζί με τα δικά του ανεβασμένα αρχεία. Το Deep Research αναζητά επίσης στον ιστό και παραθέτει και τα δύο είδη πηγών στο sources. Αν μια αναφορά Deep Research παραθέτει έγγραφο του Χώρου εργασίας που ο κάτοχος του διακριτικού δεν μπορεί πλέον να διαβάσει, η εκτέλεση επιστρέφεται ως failed με το μήνυμα “The report could not be completed. Try again.”
8.9 Αφήστε το Sophea να επιλέξει τους agents
Όταν δεν ξέρετε ποιος agent ταιριάζει, στείλτε το αίτημα χωρίς να ορίσετε agent. Το Sophea το απαντά όπως ο προεπιλεγμένος agent στη συνομιλία: μπορεί να αναζητήσει στα έγγραφα του Χώρου εργασίας που μπορεί να διαβάσει ο κάτοχος του διακριτικού, να αναζητήσει στον ιστό και να εκτελέσει οποιονδήποτε agent είναι ενεργός στον Χώρο εργασίας. Χρησιμοποιούνται μόνο agents που είναι ενεργοί στον Χώρο εργασίας.
curl -sS -X PUT "$NOUS_URL/api/external-agents/operations/leave-policy-2026" \
-H "Authorization: Bearer $NOUS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"prompt": "Summarise our leave policy and make a short presentation about it."}'Το ID λειτουργίας ακολουθεί τους ίδιους κανόνες με παραπάνω, εκτός από το ότι δεν μπορεί να είναι operations. Το σώμα περιέχει μόνο το prompt, έως 50.000 χαρακτήρες. Ελέγξτε την εκτέλεση με GET και ακυρώστε την με DELETE στην ίδια διεύθυνση. Η επανάληψη του ίδιου PUT είναι ασφαλής και επιστρέφει την ίδια εκτέλεση· διαφορετικό prompt με το ίδιο ID λειτουργίας επιστρέφει HTTP 409. Μια εκτέλεση διατηρείται για 24 ώρες.
Η απόκριση έχει τα εξής πεδία:
| Πεδίο | Σημασία |
|---|---|
status |
running όσο εργάζεται το Sophea· completed, failed ή cancelled όταν η εκτέλεση έχει ολοκληρωθεί. |
final_text |
Η απάντηση του Sophea, μόλις η εκτέλεση γίνει completed. Ένας δείκτης όπως [[1]](https://...) παραπέμπει στο στοιχείο με το ίδιο n στο sources. |
sources |
Οι πηγές που παραθέτει η απάντηση, με n, kind (web ή document), title, url και, για έγγραφο του Χώρου εργασίας, source_type. |
steps |
Κάθε agent ή εργαλείο που χρησιμοποίησε η εκτέλεση, με τη σειρά: kind (agent ή tool), name, status (completed, partial, failed ή cancelled) και notice. Ένα βήμα agent έχει επίσης τη δική του απάντηση του agent στο text και τις δικές της sources· οι αριθμοί τους αφορούν αυτό το κείμενο, όχι το final_text. |
artifacts |
Τα αρχεία που δημιούργησαν οι agents. Κατεβάστε το καθένα από το download_url του με το ίδιο διακριτικό. |
notice |
Γιατί απέτυχε μια εκτέλεση, ή null: run_interrupted (σταμάτησε ο διακομιστής που την εκτελούσε· στείλτε ξανά το ίδιο PUT για να ξεκινήσει πάλι), workspace_credits_exhausted (με renews_on) ή run_failed. Μια εκτέλεση που απέτυχε επιστρέφεται όπως είναι για το ίδιο ID λειτουργίας· για νέα προσπάθεια, χρησιμοποιήστε νέο ID λειτουργίας. |
created_at, updated_at, completed_at |
Πότε ξεκίνησε, πότε άλλαξε τελευταία φορά και πότε ολοκληρώθηκε η εκτέλεση. |
Κάθε άτομο μπορεί να έχει δέκα τέτοιες εκτελέσεις σε εξέλιξη ταυτόχρονα, επιπλέον των δέκα εκτελέσεων με επιλεγμένο agent. Μια ενδέκατη, ή μια εκτέλεση που στέλνεται όταν ο διακομιστής είναι απασχολημένος, επιστρέφει HTTP 429 με κεφαλίδα Retry-After που λέει πόσα δευτερόλεπτα να περιμένετε. Το Sophea δεν μπορεί να σας κάνει ερώτηση κατά την εκτέλεση: όταν χρειάζεται περισσότερες πληροφορίες, η απάντησή του λέει τι λείπει. Μια εκτέλεση δεν έχει δικό της συνολικό χρονικό όριο· όταν χρησιμοποιεί το Deep Research ή πολλούς agents μπορεί να διαρκέσει αρκετά λεπτά.
8.10 Αν κάτι δεν λειτουργεί
| Κατάσταση HTTP | Σημασία |
|---|---|
| 401 | Το διακριτικό λείπει, είναι λάθος ή έχει λήξει. |
| 403 | Το αίτημα αναφέρει διαφορετικό Χώρο εργασίας από αυτόν στον οποίο ανήκει το διακριτικό. |
| 404 | Ο agent ή η λειτουργία δεν υπάρχει, ή ο agent δεν είναι διαθέσιμος στον Χώρο εργασίας. |
| 409 | Το ID λειτουργίας έχει ήδη χρησιμοποιηθεί με διαφορετικό prompt, ή η πρόσβαση του κατόχου του διακριτικού σε έγγραφα άλλαξε μετά την έναρξη της εκτέλεσης. Χρησιμοποιήστε νέο ID λειτουργίας· το GET εξακολουθεί να επιστρέφει την προηγούμενη εκτέλεση. Όταν το Sophea επιλέγει τους agents, το 409 μπορεί επίσης να σημαίνει ότι ο προεπιλεγμένος agent είναι ανενεργός στον Χώρο εργασίας. |
| 413 | Το αρχείο είναι μεγαλύτερο από 100 MiB. |
| 422 | Το αίτημα δεν είναι έγκυρο: ελέγξτε το ID λειτουργίας, ότι το σώμα έχει μόνο ένα μη κενό prompt, και το μήκος του prompt. |
| 429 | Υπάρχουν πολλές εκτελέσεις σε εξέλιξη. Περιμένετε όσα δευτερόλεπτα λέει το Retry-After και στείλτε ξανά το ίδιο PUT. |
| 503 | Η εκτέλεση έχει ολοκληρωθεί, αλλά οι πηγές της δεν μπόρεσαν να ελεγχθούν αυτή τη στιγμή. Στείλτε ξανά το GET σε λίγο. |
| 502 ή 504 | Η υπηρεσία agents δεν απάντησε εγκαίρως ή δεν ήταν προσβάσιμη. Στείλτε αργότερα ξανά το ίδιο PUT· μέσα σε 24 ώρες δεν ξεκινά δεύτερη εκτέλεση. |