7  Χρήση του API συνομιλίας του Nous

Χρησιμοποιήστε το API συνομιλίας του Nous για να στείλετε μια ερώτηση από δικό σας πρόγραμμα ή εφαρμογή σε έναν Χώρο εργασίας Nous. Το αίτημα ξεκινά συνομιλία με το μοντέλο που έχει ρυθμιστεί για τον Χώρο εργασίας. Μπορεί να χρησιμοποιήσει τη γνώση και τους agents στους οποίους έχει πρόσβαση ο κάτοχος του διακριτικού.

7.1 Αποκτήστε διακριτικό και διεύθυνση Χώρου εργασίας

Δημιουργήστε ένα προσωπικό διακριτικό API ή ζητήστε από διαχειριστή Χώρου εργασίας ένα διακριτικό λογαριασμού υπηρεσίας, αν μια ενσωμάτωση χρειάζεται δική της ταυτότητα. Αντιγράψτε το διακριτικό όταν εμφανιστεί και χρησιμοποιήστε τη διεύθυνση Nous αυτού του Χώρου εργασίας. Το προσωπικό διακριτικό ενεργεί ως ο κάτοχός του, ενώ το διακριτικό υπηρεσίας ενεργεί ως ο αντίστοιχος λογαριασμός. Κανένα δεν παρέχει πρόσβαση σε έγγραφα ή agents πέρα από τα δικαιώματα της ταυτότητάς του.

Ορίστε τις παρακάτω τιμές στο τερματικό σας, αντικαθιστώντας τα παραδείγματα. Μην αποθηκεύετε το διακριτικό στον πηγαίο κώδικα ή σε κοινόχρηστα αρχεία καταγραφής.

NOUS_URL='https://nous.example.com'
NOUS_TOKEN='<paste-your-token>'

curl -sS "$NOUS_URL/api/me" \
  -H "Authorization: Bearer $NOUS_TOKEN"

Αν το /api/me δεν επιστρέψει την αναμενόμενη ταυτότητα, ελέγξτε το διακριτικό και τη διεύθυνση του Χώρου εργασίας πριν στείλετε αίτημα συνομιλίας.

7.2 Στείλτε το πρώτο μήνυμα

Αυτό το αίτημα ξεκινά συνομιλία με τον προεπιλεγμένο agent. Το message είναι η ερώτηση ή η οδηγία που θέλετε να απαντήσει ο βοηθός.

curl -sS "$NOUS_URL/api/chat/send-chat-message" \
  -H "Authorization: Bearer $NOUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Συνοψίστε την πολιτική εισαγωγής μας",
    "knowledge_search_enabled": true,
    "stream": false
  }'

Το knowledge_search_enabled: true επιτρέπει στον agent να αναζητήσει, όταν χρειάζεται, σε ευρετηριασμένες πηγές στις οποίες έχει πρόσβαση ο κάτοχος του διακριτικού. Δεν επιβάλλει αναζήτηση. Χρειάζεται επίσης ενεργό εργαλείο αναζήτησης και κατάλληλο εύρος γνώσης. Το stream: false επιστρέφει μία απόκριση JSON, πιο εύχρηστη για μια πρώτη ενσωμάτωση.

7.3 Επιλέξτε παραμέτρους αιτήματος

Πεδίο	Τι κάνει	Αν παραλειφθεί
message	Το μήνυμα προς τον βοηθό. Υποχρεωτικό.	Το αίτημα είναι άκυρο.
knowledge_search_enabled	Το true επιτρέπει στον agent να αναζητήσει σε επιτρεπόμενη γνώση όταν είναι χρήσιμο· το false απενεργοποιεί την αυτόματη αναζήτηση.	Δεν ζητείται αναζήτηση γνώσης.
stream	Το false επιστρέφει μία απόκριση JSON· το true επιστρέφει αντικείμενα JSON, ένα ανά γραμμή.	true: η απόκριση είναι ροή γραμμών JSON, όχι ένα αντικείμενο JSON.
chat_session_info	Ξεκινά νέα συνομιλία. Προσθέστε {"persona_id":123} για να επιλέξετε διαθέσιμο agent.	Ξεκινά νέα συνομιλία με τον προεπιλεγμένο agent, εφόσον παραλείπεται και το chat_session_id.
chat_session_id	Συνεχίζει υπάρχουσα συνομιλία με το ID που επέστρεψε προηγούμενη απόκριση.	Ξεκινά νέα συνομιλία, εφόσον παραλείπεται και το chat_session_info.
include_citations	Το false αφαιρεί τις παραπομπές από το κείμενο της απάντησης.	true: περιλαμβάνονται παραπομπές όταν είναι διαθέσιμες.

Στείλτε είτε chat_session_info είτε chat_session_id, ποτέ και τα δύο στο ίδιο αίτημα. Για συνήθη χρήση, ξεκινήστε με το πρώτο παράδειγμα και προσθέστε παράμετρο μόνο όταν τη χρειάζεστε.

Με stream: true, ο τύπος περιεχομένου HTTP είναι text/event-stream, αλλά το σώμα περιέχει JSON σε ξεχωριστές γραμμές αντί για συμβάντα data:. Διαβάστε κάθε γραμμή ως ένα αντικείμενο JSON.

7.4 Διαβάστε την απόκριση

Με stream: false, η απόκριση JSON περιλαμβάνει την απάντηση. Η πρώτη απόκριση μιας νέας συνομιλίας περιλαμβάνει επίσης το chat_session_id. Αποθηκεύστε αυτό το ID και συνεχίστε να το χρησιμοποιείτε στα επόμενα μηνύματα· οι επόμενες αποκρίσεις μπορεί να περιέχουν "chat_session_id": null. Ακολουθεί απόσπασμα· τα αντικείμενα εγγράφων περιέχουν περισσότερα πεδία στην πραγματική απόκριση.

{
  "answer": "Η πολιτική απαιτεί επικοινωνία την πρώτη εβδομάδα. [1]",
  "chat_session_id": "cba35529-7e57-4c57-8f84-0c9733277f5c",
  "message_id": 42,
  "top_documents": [
    {
      "document_id": "onboarding-policy",
      "semantic_identifier": "Πολιτική εισαγωγής"
    }
  ],
  "citation_info": [
    {
      "type": "citation_info",
      "citation_number": 1,
      "document_id": "onboarding-policy"
    }
  ],
  "error_msg": null
}

Το top_documents περιέχει πηγές που ανακτήθηκαν και το citation_info συνδέει αριθμημένες παραπομπές με έγγραφα. Μια απάντηση μπορεί να μην έχει παραπομπές αν ο agent δεν ανέκτησε πηγή. Ελέγξτε το error_msg πριν χρησιμοποιήσετε το answer: ένα αίτημα συνομιλίας μπορεί να επιστρέψει HTTP 200 μαζί με σφάλμα στην απόκριση. Τα error_code και error_is_retryable δίνουν περισσότερες πληροφορίες όταν συμβεί αυτό.

7.5 Συνεχίστε τη συνομιλία

Χρησιμοποιήστε το chat_session_id της πρώτης απόκρισης σε κάθε επόμενο μήνυμα της ίδιας συνομιλίας. Αντικαταστήστε το ενδεικτικό ID με αυτό που επέστρεψε το πρώτο σας αίτημα. Μην αντικαταστήσετε το αποθηκευμένο ID με την τιμή null μιας επόμενης απόκρισης.

curl -sS "$NOUS_URL/api/chat/send-chat-message" \
  -H "Authorization: Bearer $NOUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Τι πρέπει να κάνει μετά ο προϊστάμενος;",
    "chat_session_id": "cba35529-7e57-4c57-8f84-0c9733277f5c",
    "knowledge_search_enabled": true,
    "stream": false
  }'

7.6 Ξεκινήστε με άλλον agent

Δείτε τους agents που είναι διαθέσιμοι για το διακριτικό σας και χρησιμοποιήστε ένα ID agent στο πρώτο μήνυμα νέας συνομιλίας:

curl -sS "$NOUS_URL/api/agents?page_size=100" \
  -H "Authorization: Bearer $NOUS_TOKEN"

curl -sS "$NOUS_URL/api/chat/send-chat-message" \
  -H "Authorization: Bearer $NOUS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message": "Συνοψίστε την πολιτική εισαγωγής μας",
    "chat_session_info": {"persona_id": 123},
    "knowledge_search_enabled": true,
    "stream": false
  }'

Αντικαταστήστε το 123 με το ID διαθέσιμου agent. Για επόμενα μηνύματα προς τον ίδιο agent, χρησιμοποιήστε το chat_session_id που επιστράφηκε αντί για chat_session_info.

7.7 Αν κάτι δεν λειτουργεί

• Αποτυχία ταυτοποίησης ή πρόσβασης: ελέγξτε τη διεύθυνση του Χώρου εργασίας, τη λήξη του διακριτικού και την πρόσβαση του κατόχου του στον Χώρο εργασίας και τον agent. Μη στέλνετε το διακριτικό στην υποστήριξη μέσα σε εικόνα ή μήνυμα.
• Η απόκριση περιέχει γραμμές JSON αντί για ένα αντικείμενο JSON: ορίστε "stream":false στο σώμα του αιτήματος.
• Η απάντηση δεν έχει παραπομπές γνώσης: στείλτε "knowledge_search_enabled":true, βεβαιωθείτε ότι ο κάτοχος του διακριτικού έχει πρόσβαση στην πηγή και ελέγξτε ότι ο agent διαθέτει ενεργό εργαλείο αναζήτησης. Ο agent μπορεί και πάλι να κρίνει ότι δεν χρειάζεται αναζήτηση. Δείτε την Αναζήτηση γνώσης για το εύρος αναζήτησης.
• Το αίτημα HTTP ολοκληρώνεται, αλλά η απάντηση δεν είναι αξιοποιήσιμη: ελέγξτε τα error_msg, error_code και error_is_retryable στην απόκριση JSON πριν τη θεωρήσετε επιτυχημένη.