Documentazione Invantive
Forum di supporto InvantiveAccedi / Registrati

Strumenti

Invantive MCP Server offre i seguenti strumenti a un client AI come Anthropic Claude. Gli strumenti su un database sono di sola lettura: non modificano dati e non eseguono istruzioni SQL. Solo check_sql ne accetta uno, che lo analizza senza eseguirlo. Gli strumenti di stato operano su una pagina di stato di Invantive Cloud Status invece che su un database; quattro di essi modificano la pagina di stato.

  • describe_entities: elenca le entità che possono essere lette dal database, con il loro nome, etichetta, tipo, contenitore dei dati e l'ordine di grandezza del numero delle righe. Disponibile a partire dalla versione 26.0. Vedi sotto.
  • describe_entity: descrive un'entità in modo completo, con i suoi campi, la chiave primaria, le chiavi univoche, le chiavi esterne e la velocità prevista. Disponibile a partire dalla versione 27.0. Vedi sotto.
  • read_records: legge le righe di una entità, con select, filtro, ordinamento e numero di righe nella notazione dell'interfaccia di query OData versione 4. Disponibile a partire dalla versione 26.0. Vedi sotto.
  • analyze_records: esegue la stessa lettura di read_records e restituisce come è stata eseguita invece delle righe. Disponibile a partire dalla versione 28.0. Vedi sotto.
  • current_cloud_user: restituisce il profilo dell'utente connesso e dell'organizzazione di tale utente, come conservato in Invantive Cloud. Disponibile a partire dalla versione 26.0. Vedi sotto.
  • check_sql: verifica la sintassi delle istruzioni Invantive UniversalSQL e PSQL senza eseguirle. Disponibile a partire dalla versione 28.0. Vedi sotto.
  • status_get_summary: restituisce in sintesi lo stato della pagina di stato. Vedi sotto.
  • status_list_incidents: elenca gli incidenti della pagina di stato, dal più recente. Vedi sotto.
  • status_get_incident: restituisce un incidente con i suoi componenti e aggiornamenti. Vedi sotto.
  • status_create_incident: apre un incidente sulla pagina di stato. Vedi sotto.
  • status_add_update: pubblica un aggiornamento su un incidente, che può risolverlo. Vedi sotto.
  • status_set_component_state: imposta lo stato di un componente. Vedi sotto.
  • status_schedule_maintenance: pianifica la manutenzione con una finestra temporale. Vedi sotto.

Istruzioni per il client

Quando un client AI si connette, il server gli invia le istruzioni. Indicano la versione del server e gli indirizzi con cui lo stesso database è disponibile per altri client, con l'indicazione se l'utente ha attivato ciascun indirizzo: Invantive MCP Server, il protocollo SQL Server di Invantive UniversalSQL Server per client SQL Server e ODBC, Bridge Online per Power BI e App Online per applicazioni, entrambi tramite OData versione 4. Forniscono anche consigli per leggere in modo efficiente, indicano i limiti di frequenza delle piattaforme e rimandano a Invantive Data Hub.

Le istruzioni indicano inoltre che Invantive Cloud può scambiare dati tra il database e altre piattaforme, replicandoli, combinandoli o integrandoli. Elencano i nomi commerciali di quelle piattaforme, come Exact Online, Salesforce e AFAS Profit. L'elenco contiene le piattaforme per le quali Invantive Cloud dispone di un driver. Sono esclusi i driver di test, gli helper, i driver obsoleti e i prodotti propri di Invantive. L'elenco è disponibile dalla release 27.0.

Elenco delle entità

describe_entities elenca le entità del database che possono essere lette, in modo che un client AI possa sceglierne una. Non descrive un'entità in modo completo: describe_entity lo fa per una sola entità. Lo strumento accetta due argomenti, entrambi facoltativi:

  • entities: i nomi delle entità da elencare. Un nome viene confrontato senza distinzione tra maiuscole e minuscole e deve essere scritto come restituito in una risposta precedente. Al posto di un array si accetta un singolo nome o un elenco separato da virgole.
  • nameOnly: se impostato su true, ogni entità viene ridotta al proprio nome, etichetta, tipo e contenitore di dati. Usarlo solo quando la risposta è stata troncata. Il valore predefinito è false.

La risposta contiene:

  • database: il segmento URL del database.
  • detailLevel: summary, oppure namesOnly quando si applica nameOnly.
  • entityCount e returnedEntityCount: il numero di entità che corrispondono alla richiesta e il numero di entità nella risposta.
  • truncated e truncationHint: presenti quando la risposta contiene meno entità di quelle corrispondenti. Il suggerimento spiega come porre una domanda più mirata, indicando in entities le entità di interesse.
  • unknownEntities e unknownEntitiesHint: presenti quando entities contiene un nome che non esiste. Il suggerimento indica le entità esistenti più vicine per al massimo i primi cinque nomi sconosciuti. unknownEntitiesHint è disponibile dalla release 27.0.
  • dataContainers: un oggetto per ogni contenitore di dati, poiché il partizionamento appartiene al contenitore di dati e non all'entità. Contiene il alias che un nome di entità porta dopo il @, il provider che serve al contenitore dei dati e se esso supportsPartitions. Un contenitore di dati che supporta le partizioni contiene anche partitionLabelPlural, partitionCount, selectedPartitionCount e allPartitionsSelected: il termine che la piattaforma usa per più partizioni, come le divisioni in Exact Online, il numero di partizioni disponibili, il numero che una chiamata di read_records interroga e se si tratta di tutte.
  • partitioningNote: come il partizionamento si relaziona alle entità di questo database. Presente quando almeno un contenitore di dati supporta le partizioni.
  • selectedPartitionCountTotal: il numero di partizioni selezionate su tutti i contenitori di dati.
  • entities: un oggetto per entità, ordinato per contenitore di dati e poi per nome, in modo che una risposta troncata ometta le stesse entità a ogni chiamata.

Un'entità contiene:

  • name: il nome da passare nell'argomento entity di read_records e describe_entity.
  • label: l'etichetta che la piattaforma usa per il contenuto. Presente solo quando differisce da name.
  • type: il tipo di oggetto, come table, view o tablefunction.
  • dataContainer: l'alias del contenitore di dati che contiene l'entità.
  • rowCountBand: l'ordine di grandezza del numero di righe, quando la piattaforma fornisce una stima. Il valore è empty, <=100, <=1k, <=10k, <=100k, <=1M oppure >1M.
  • notReadable: vero quando l'entità non può essere letta. Altrimenti assente.

I membri rowCountBand e notReadable sono omessi quando si applica nameOnly.

Fino alla release 26.0 inclusa, ogni entità conteneva anche description, keyField e partitionSpecific, e un contenitore di dati conteneva l'intero partizionamento: i termini, la colonna di partizione e le partizioni selezionate. A partire dalla release 27.0 questi sono presenti nella risposta di describe_entity. Questo mantiene l'elenco breve e veloce su un database con più di mille entità.

La dimensione della risposta è limitata a 60,000 caratteri per impostazione predefinita. L'impostazione MaxDescribeEntitiesResponseChars modifica quel limite. È disponibile dalla release 26.0. L'impostazione MaxEntityDescriptionChars non viene più usata dalla release 27.0, poiché l'elenco non contiene descrizioni.

I seguenti argomenti elencano due entità del database:

{ "entities": [ "SalesInvoices", "Accounts" ] }

Descrizione di un'entità

describe_entity descrive un'entità in modo completo. Un client AI la chiama con un nome di describe_entities, prima di leggere l'entità con read_records. È disponibile dalla release 27.0. Lo strumento accetta un argomento:

  • entity: il nome dell'entità, così come lo restituisce describe_entities. Un nome viene confrontato senza distinzione tra maiuscole e minuscole. Obbligatorio.

Un nome che non esiste viene rifiutato con il codice messaggio itgenmcp665. Il suggerimento indica le entità esistenti più vicine.

La risposta contiene:

  • database: il segmento URL del database.
  • name, label, labelSingular, type e dataContainer: come nell'elenco. label e labelSingular sono presenti solo quando differiscono da name.
  • description: cosa contiene l'entità, descritto per un utente aziendale e in modo completo. documentation è una spiegazione aggiuntiva, quando la piattaforma la fornisce.
  • partitionSpecific: vero quando il contenuto dipende dalle partizioni selezionate. Altrimenti assente.
  • notReadable: vero quando l'entità non può essere letta. Altrimenti assente.
  • rowCountBand e estimatedRowCount: l'ordine di grandezza del numero di righe e la stima stessa, quando la piattaforma ne fornisce una. Una stima non è un conteggio.
  • performance: cosa aspettarsi in termini di velocità di lettura dell'entità.
  • primaryKey, uniqueKeys e foreignKeys: le chiavi e le relazioni con altre entità.
  • dataContainerDetails e partitioningNote: il contenitore di dati che contiene l'entità e come il partizionamento si relaziona all'entità.
  • fieldCount, returnedFieldCount, truncated e truncationHint: il numero dei campi, il numero nella risposta e, quando dei campi sono esclusi, cosa fare al riguardo.
  • fields: i campi dell'entità.

Un campo contiene:

  • name: il nome così come lo accettano gli argomenti select, filter e orderby di read_records.
  • label: l'etichetta usata dalla piattaforma. Presente solo quando differisce da name.
  • dataType: il tipo primitivo 4 della versione OData, come String, Int32, Decimal, DateTimeOffset, Boolean o Guid.
  • nullable: se il campo può essere vuoto.
  • maxLength, precision e scale: la lunghezza di un campo testo o binario e le cifre di un campo decimale, quando la piattaforma le indica.
  • primaryKey: true quando il campo fa parte della chiave primaria. Altrimenti assente.
  • description: cosa contiene il campo, descritto per un utente aziendale.
  • filterOnPlatform: vero quando la piattaforma stessa valuta un filtro sul campo, in modo che vengano recuperate solo le righe corrispondenti. Falso quando ogni riga viene recuperata prima e filtrata successivamente, il che è lento su un'entità di grandi dimensioni.
  • sortOnPlatform: vero quando la piattaforma stessa ordina in base al campo. Assente quando non è noto.

I membri uniqueKeys e foreignKeys, e il guarantee di una chiave, sono disponibili dalla versione 28.0. La release 27.0 risponde per la chiave primaria senza garanzia, poiché il suo motore non conserva altri metadati di chiave.

Una chiave contiene fields, guarantee e, quando la piattaforma ne fornisce una, name. La garanzia è enforced quando la piattaforma stessa mantiene la chiave univoca, e declared quando il driver o il modello la dichiara senza che la piattaforma la imponga. I campi di una chiave sono denominati come i campi dell'entità. Un nome che non è un campo dell'entità viene scritto come la piattaforma denomina la colonna. Una chiave che ripete la chiave primaria non viene elencata in uniqueKeys.

Una chiave esterna è una relazione da campi di questa entità alla chiave di un'altra entità. Contiene:

  • fields: i campi di questa entità che contengono il riferimento.
  • referencedEntity e referencedFields: l'entità a cui si fa riferimento, come la denomina describe_entities, e i suoi campi, nello stesso ordine di fields.
  • referencedTable: il nome che la piattaforma assegna all'oggetto a cui si fa riferimento. Presente solo quando quell'oggetto non è un'entità di questo database; in tal caso referencedFields contiene i nomi delle colonne della piattaforma.
  • kind: key quando i campi si riferiscono a una chiave dell'entità referenziata, textual quando la relazione esiste solo a parole e vale a determinate condizioni, e candidate quando risulta dai nomi dei campi e vale nei dati senza che la piattaforma lo dichiari.
  • guarantee: enforced o declared, come per una chiave.
  • description: indica quando una relazione textual o candidate è valida. Una relazione di questi tipi non vale per ogni riga.
  • name: il nome della chiave esterna sulla piattaforma, quando ne ha una.

Questo server legge un'entità per chiamata e non esegue join. Un client AI legge le righe correlate con una seconda chiamata di read_records, filtrando sui valori di fields.

Le prestazioni contengono i seguenti membri, quando il driver della piattaforma li indica:

  • accessLatencyMs: il tempo medio di un viaggio di andata e ritorno verso la piattaforma, in millisecondi.
  • fullScanRowsPerMinute: il numero medio di righe al minuto quando viene letta l'intera entità.
  • pointQueryRowsPerMinute: il numero medio di righe al minuto quando le righe vengono lette tramite un filtro su una chiave.
  • estimatedFullScanSeconds: una stima del tempo necessario a leggere ogni riga dell'entità, da estimatedRowCount e fullScanRowsPerMinute. È presente solo quando entrambi i valori sono noti.

I valori sono medie statiche del driver per la piattaforma e non misurazioni di questo database. Il valore per la scrittura non viene restituito, poiché il server esegue solo letture. Un driver che non dichiara alcun dato lascia fuori performance.

La dimensione della risposta è limitata a 60,000 caratteri per impostazione predefinita. L'impostazione MaxDescribeEntityResponseChars modifica tale limite e MaxSelectedPartitionsDescribed il numero di partizioni elencate in dataContainerDetails. Entrambi sono disponibili dalle versioni 27.0 e 26.0 rispettivamente. Quando i campi non entrano, hanno la precedenza i campi delle chiavi. Le chiavi, le relazioni e le prestazioni non vengono mai omesse.

I seguenti argomenti descrivono un'entità del database:

{ "entity": "SalesInvoices" }

Lettura dei record

read_records legge le righe di una sola entità. Un client AI lo richiama una volta che describe_entities ha indicato quale entità contiene i dati e describe_entity ne ha elencato i campi. Lo strumento accetta i seguenti argomenti:

  • entity: il nome dell'entità, così come lo restituisce describe_entities. Obbligatorio.
  • select: un elenco di nomi di campo separati da virgole, come li restituisce describe_entity, nella notazione $select dell'interfaccia di query della versione 4 di OData.
  • filter: la condizione che le righe devono soddisfare, nella notazione $filter, con gli operatori eq, ne, gt, ge, lt, le, and, or e not.
  • orderby: un elenco di campi con una direzione, nella notazione $orderby, ad esempio AmountDC desc.
  • first: il numero massimo di righe da leggere. Se omesso, vengono letti tutti i record che corrispondono al filtro.

La lettura viene tradotta in un'istruzione select ed eseguita con l'autorizzazione dell'utente connesso. Le righe vengono restituite come contenuto strutturato, un oggetto per riga con i campi selezionati. Non esiste cursore né paginazione. Un client AI passa first a meno che non voglia l'intero insieme, e restringe la risposta con filter e orderby.

Un campo o un letterale che il parser OData non riconosce viene rifiutato con il codice messaggio itgenmcp640. Quando il rifiuto riguarda un campo, il suggerimento indica i campi dell'entità più simili. Date e numeri sono scritti senza virgolette.

I seguenti argomenti leggono le cinque fatture aperte più grandi di un'entità:

{ "entity": "SalesInvoices"
, "select": "InvoiceNumber,AmountDC"
, "filter": "Status eq 20"
, "orderby": [ "AmountDC desc" ]
, "first": 5
}

Analisi di una lettura

analyze_records accetta gli argomenti di read_records: entity, obbligatorio, e select, filter, orderby e first. La lettura viene tradotta nella stessa istruzione select, eseguita con la stessa autorizzazione e registrata allo stesso modo. Le sue righe vengono lette e contate, ma non restituite. La risposta contiene:

  • sqlStatement: l'istruzione select che è stata eseguita.
  • rowsReturned e rowsRead: le righe restituite dall'istruzione e le righe lette da tutte le tabelle.
  • counters: ciò che l'istruzione ha contato, sommato su tutti i passi, come PairsEvaluated o RowsSorted; solo i contatori diversi da zero.
  • steps: un oggetto per ogni passo dell'esecuzione, come la lettura di una tabella, un join o un ordinamento, con gli stessi membri di una riga del file /steps di Invantive Data Hub: il tipo e la descrizione del passo, le righe in ingresso e in uscita, la durata, il tempo di processore e l'allocazione, inclusi i passi successivi, le stesse cifre senza i passi successivi come le misura explain analyze, come un join ha abbinato le sue righe, il numero di righe dichiarate da una tabella e i contatori del passo stesso. I membri di un passo sono scritti come in quella riga, con l'iniziale maiuscola, come ExclusiveCpuMs.

Un client AI la chiama quando una lettura è lenta o legge più righe di quante ne restituisce, ad esempio per verificare se un filtro è stato passato al contenitore dati, quale algoritmo di join è stato scelto o quale passo ha allocato la memoria. Misurare ogni passo costa una lettura del tempo di processore per riga per passo, che solo questo strumento sostiene.

I seguenti argomenti analizzano la lettura delle cinque fatture aperte più grandi di un'entità, con gli stessi argomenti che userebbe read_records:

{ "entity": "SalesInvoices"
, "select": "InvoiceNumber,AmountDC"
, "filter": "Status eq 20"
, "orderby": [ "AmountDC desc" ]
, "first": 5
}

Lettura dell'utente corrente

current_cloud_user restituisce il profilo dell'utente connesso e dell'organizzazione di tale utente, come è registrato in Invantive Cloud. Un client AI lo invoca quando la risposta dipende da chi chiede o dall'organizzazione a cui appartengono i dati. Lo strumento non accetta argomenti e non legge nulla dal database.

La risposta contiene i seguenti membri dell'utente:

  • Uid, Iwid e CognitoUserId: gli identificativi dell'utente, dell'utente web e nel provider di identità.
  • Name, GivenName e FamilyName: il nome completo, il nome e il cognome.
  • Gender: M per maschio, F per femmina e U per sconosciuto.
  • JobTitle: la qualifica professionale.
  • EmailAddress, PhoneNumber e MobileNumber: come raggiungere l'utente.
  • LanguageCode: la lingua nel formato ISO 639-1. La lingua predefinita del servizio viene usata quando l'utente non ne ha una.
  • CreatedUtc e ModifiedUtc: quando l'utente è stato creato e ultimamente modificato.
  • LogInStartUtc e LogInEndUtc: il periodo in cui l'utente può accedere.
  • UserIconUrl e UserIcon: la miniatura dell'utente come indirizzo e in forma binaria.

La risposta contiene i seguenti membri dell'organizzazione dell'utente:

  • PartyName: il nome dell'organizzazione. Si usa prima il nome nel profilo dell'utente, e il nome detenuto dall'organizzazione stessa quando il profilo non ne ha uno. La soluzione di ripiego è disponibile a partire dalla release 27.0.
  • PartyAddressLine1, PartyAddressLine2, PartyAddressLine3, PartyPostalCode, PartyCity e PartyCountry: l'indirizzo. Viene usato per primo il paese dell'organizzazione e, quando l'organizzazione non ne ha uno, il paese indicato nel profilo dell'utente. La soluzione di ripiego è disponibile a partire dalla release 27.0.
  • PartyEmailAddress, PartyPhone e PartyWebSite: come raggiungere l'organizzazione.
  • PartyLegalStructure: la forma giuridica, ad esempio NL-BV.
  • PartyCoCNumber, PartyVatNumber, PartyIban e PartyBic: il numero di iscrizione alla Camera di Commercio, il numero di partita IVA, l'IBAN e il BIC.

I membri PartyCurrencyCode, PartyState, PartyGlnNumber, PartyRsinNumber, PartySiretNumber, PartyPaypalIdentifier e PartyWageTaxNumber fanno parte della risposta, ma il servizio non li compila. Invantive Cloud non contiene alcun valore per essi.

Verifica della sintassi di SQL

check_sql analizza una o più istruzioni Invantive UniversalSQL e PSQL, separate da ;, senza eseguirle e senza leggere il database. Un client AI lo richiama su un'istruzione che ha scritto per Invantive Data Hub, Invantive Query Tool o uno script, prima che l'istruzione consumi un budget o modifichi i dati. I nomi di tabelle e colonne non vengono verificati, poiché ciò richiede il database. Disponibile a partire dalla versione 28.0.

Lo strumento accetta un argomento, sql, di al massimo 1,000,000 caratteri. La risposta contiene:

  • Valid: true quando le istruzioni seguono la grammatica.
  • MessageCode, Message e Hint: l'errore di sintassi, il relativo messaggio con un estratto e i caratteri di evidenziazione, e cosa fare. I codici sono spiegati in Syntax Errors.
  • Url: l'indirizzo della sezione del codice messaggio in Syntax Errors.
  • Position: Line e Column, contati da 1 con una tabulazione come una colonna, Offset, contati da 0 nel testo, e Length, il numero di caratteri contrassegnati.
  • Syntax: Kind come missing o premature-end, Expected con ciò che è valido nella posizione come elenco di elementi non tradotti come FROM, ,, name o expression, e Context con la parte dell'istruzione come whereClause.

Un errore di sintassi è la risposta dello strumento e non un suo guasto: il risultato non è contrassegnato come errore.

Strumenti su Invantive Cloud Status

Gli strumenti di stato consentono a un client AI di leggere e gestire una pagina di stato di Invantive Cloud Status, ad esempio per rispondere se un servizio è non disponibile o per segnalare un'interruzione. Sono offerti solo su un server in cui sono impostate le impostazioni StatusPage:Server e StatusPage:ApiToken: l'indirizzo del server di stato, come https://statuspage.invantive.eu, e un token API di un tenant, creato in "Settings" e "API tokens". StatusPage:TimeoutSec imposta il numero di secondi che una chiamata può durare, con un valore predefinito di 20. Gli strumenti non sono ancora rilasciati.

Gli strumenti operano sulle pagine del tenant del token. Per i tre strumenti di sola lettura è sufficiente un token con ambito read. I quattro strumenti che modificano la pagina di stato richiedono un token con ambito write; con un token con ambito read il server di stato li rifiuta. Una modifica è subito visibile ai lettori e può inviare notifiche agli abbonati, quindi il client AI è istruito a confermare il testo con l'utente prima di invocarlo.

Gli stati di un componente sono operational, degraded_performance, partial_outage, major_outage e under_maintenance. Le fasi di un incidente sono investigating, identified, monitoring e resolved.

status_get_summary non accetta argomenti. La risposta contiene:

  • overallState: lo stato più grave tra i componenti che contano per lo stato complessivo.
  • componentCount: il numero di componenti.
  • componentsNotOperational: per ogni componente non operativo il suo codice component, name, state e il momento since in cui si trova in tale stato.
  • openIncidents: per ogni incidente non risolto il suo publicId, title, phase, impact e startedAt.
  • maintenance: la manutenzione in corso o pianificata entro sette giorni, con publicId, title, phase, windowStart e windowEnd.

status_list_incidents accetta due argomenti facoltativi:

  • openOnly: se vero, solo gli incidenti non risolti. Il valore predefinito è false.
  • first: il numero degli incidenti più recenti da restituire, da 1 a 100. Il valore predefinito è 20.

La risposta contiene incidents, con gli stessi membri per incidente di openIncidents di status_get_summary.

status_get_incident assume il publicId di un incidente, come 2026-0187. La risposta è l'incidente così come lo restituisce l'API di gestione del server di stato, con i componenti interessati e il loro stato, la cronologia degli aggiornamenti con la loro fase e la loro versione.

status_create_incident accetta:

  • title: il titolo visualizzato dai lettori. Obbligatorio.
  • message: il primo aggiornamento, per i clienti.
  • impact: uno tra none, minor, major o critical. Il valore predefinito è minor.
  • phase: la fase del primo aggiornamento. Il valore predefinito è investigating.
  • template: il codice di un modello di incidente, che compila ciò che non viene indicato.
  • components: i componenti interessati, ciascuno con il proprio codice component e lo state che riceve mentre l'incidente è aperto.

status_add_update accetta:

  • publicId: l'identificativo pubblico dell'incidente. Obbligatorio.
  • message: il testo dell'aggiornamento, per i clienti. Obbligatorio.
  • phase: la fase dell'aggiornamento. Obbligatorio. La fase resolved chiude l'incidente e riporta i suoi componenti allo stato operativo.
  • internalNote: una nota solo per gli operatori, che non viene mai pubblicata né inviata.

status_set_component_state accetta:

  • component: il codice del componente, come lo restituisce status_get_summary. Obbligatorio.
  • state: il nuovo stato. Obbligatorio.
  • hold: quando è vero, le sonde non cambiano lo stato finché un operatore non lo rilascia. Il valore predefinito è true.

status_schedule_maintenance accetta:

  • title: il titolo visualizzato dai lettori. Obbligatorio.
  • message: cosa succede e cosa notano i lettori. Obbligatorio.
  • windowStart e windowEnd: l'inizio e la fine della finestra come data e ora ISO 8601 con fuso orario, come 2026-11-08T06:00:00+01:00. Obbligatorio.
  • components: i codici dei componenti interessati.
  • autoStart: avvia la manutenzione all'inizio della finestra. Il valore predefinito è true.
  • autoComplete: completa la manutenzione alla fine della finestra. Il valore predefinito è true.
  • muteProbes: silenzia le sonde dei componenti interessati durante la finestra. Il valore predefinito è true.

Gli strumenti che modificano la pagina di stato restituiscono l'incidente, il componente o la manutenzione così come il server di stato li restituisce dopo la modifica.

Tracciare la dimensione di una risposta

Invantive MCP Server scrive nella traccia la dimensione di ogni risposta in caratteri. La dimensione è la quantità della riga di traccia con codice messaggio itgenmcp664, scritta al livello debug. Somma il contenuto strutturato e i blocchi di testo della risposta; il messaggio indica lo strumento, il database e entrambe le parti. La riga viene scritta sia per una risposta riuscita sia per una non riuscita, poiché il client AI le legge entrambe nel proprio contesto. La busta del messaggio JSON-RPC non viene conteggiata. Disponibile a partire dalla versione 27.0.

Quando uno strumento non funziona

Uno strumento che fallisce risponde con isError impostato e i dettagli nel contenuto strutturato, in modo che il client AI possa indicare all'utente cosa fare. La risposta contiene:

  • Message e MessageCode: cosa è andato storto e il codice da citare quando si chiede assistenza.
  • KindRequest: il suggerimento, cioè il passo successivo per il client AI o per l'utente. Ogni risposta ne ha una. Quando non è noto un suggerimento specifico, indica se inviare di nuovo la richiesta, correggerla o informarne l'utente.
  • NaturalKey: l'oggetto del messaggio, come il database o l'entità richiesta.
  • IsRecoverable: vero quando inviare nuovamente la stessa richiesta più tardi può avere successo, falso quando non può. Viene omesso quando nulla indica né l'uno né l'altro.
  • RetryAfterSec: il numero di secondi che il servizio consiglia di attendere prima di inviare di nuovo la stessa richiesta, da un blocco temporaneo o dall'intestazione Retry-After della piattaforma. È presente solo quando IsRecoverable è vero e è stata consigliata un'attesa; nessuna attesa viene inventata. Quando l'attesa supera 60 secondi, il suggerimento indica al client AI di lasciare l'attesa all'utente. Disponibile a partire dalla versione 27.0.
  • Actor: chi deve agire per primo. ai quando il client AI può correggere la richiesta o attendere e inviarla di nuovo, user quando una persona deve decidere o agire al di fuori della conversazione, ad esempio su una licenza, un indirizzo IP o un accesso, e forums quando nessuno può risolvere il problema nella conversazione, quindi il riferimento e il codice messaggio vanno cercati o segnalati nei forum. Un'attesa superiore a 60 secondi è a carico dell'utente. Disponibile a partire dalla versione 27.0.
  • HelpUrl: l'indirizzo della discussione del forum o della pagina di aiuto sul codice del messaggio, quando è noto. Disponibile a partire dalla versione 27.0.
  • Uid: il riferimento dell'errore, da citare al supporto.

Una richiesta per un'entità o un campo inesistente indica nel suggerimento i nomi esistenti più simili. describe_entities fa lo stesso per i nomi nel suo argomento entities, in unknownEntitiesHint. Entrambi sono disponibili dalla versione 27.0.

Una richiesta da un indirizzo IP non autorizzato per il database viene rifiutata con il codice messaggio itgenmcp326. Il messaggio indica l'indirizzo e il suggerimento indica il database a cui deve essere aggiunto.

Uno strumento di stato che fallisce risponde allo stesso modo. Quando il server di stato rifiuta la chiamata, MessageCode contiene il codice di messaggio del server di stato, oppure itgenmst001 quando la risposta non ne contiene alcuno. Un rifiuto per mancanza dell'ambito write indica all'utente di richiedere un token con ambito write. itgenmst002 significa che gli strumenti di stato non sono configurati sul server, e itgenmst003 che il server di stato non è raggiungibile.

Note di rilascio