Primi passi

Panoramica

Questo esempio usa web_search per preparare una chiave, ottenere un preventivo gratuito, eseguire e recuperare il risultato. Bastano una shell compatibile con Bash e cURL, senza SDK specifici.

Prerequisiti

Prepara questi cinque elementi:

Un account NoimosAI con accesso a Developer Platform
Un progetto Developer Platform con accesso API abilitato
Una chiave sviluppatore con prefisso nmp_ e autorizzazioni necessarie
Una shell compatibile con Bash
cURL, jq e uuidgen

Per attività a pagamento verifica anche saldo prepagato in USD e limiti mensili del progetto. Le autorizzazioni sono illustrate in Autenticare le richieste. Se non compare alcun progetto accessibile, chiedi a un OWNER o ADMIN dell’organizzazione di crearne uno o aggiungerti. Le chiavi si creano nei progetti di cui fai parte.

Eseguire l’API

Segui questi sette passaggi per la prima esecuzione.

1. Creare una chiave in Developer Platform

Un ADMIN o DEVELOPER del progetto può creare una chiave in Developer Platform:

Accedi e seleziona il progetto.
Apri Chiavi API e scegli Crea nuova chiave.
Imposta nome descrittivo, scadenza e autorizzazioni, quindi crea la chiave.
Salva la chiave segreta in un luogo sicuro: viene mostrata una sola volta.

Questa guida richiede project:read, tools:read, tools:execute e executions:read. Per altri usi concedi solo le autorizzazioni necessarie.

2. Impostare chiave e URL di base

Salva chiave e URL di base in variabili d’ambiente per evitare segreti direttamente nella cronologia o nel codice sorgente.

export NOIMOS_PLATFORM_API_URL="https://api.noimosai.com/noimosToolBridge"
export NOIMOS_PLATFORM_API_KEY="nmp_..."

La chiave viene mostrata solo alla creazione. Non salvarla in Git, documenti condivisi o JavaScript lato client.

3. Verificare il progetto della chiave

Verifica prima che la chiave corrisponda al progetto previsto di Developer Platform.

curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/project" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY"

La risposta include in data ID organizzazione, ID e nome progetto. Se il progetto non è quello previsto, verifica la chiave prima di eseguire attività a pagamento.

{
  "data": {
    "developerOrganizationId": "...",
    "developerProjectId": "...",
    "name": "Example Project"
  },
  "requestId": "..."
}

4. Consultare gli strumenti disponibili

Recupera nomi, descrizioni, schemi, esempi, disponibilità e prezzi attuali.

NOIMOS_TOOLS_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

echo "$NOIMOS_TOOLS_RESPONSE" | jq

Verifica executionEnabled nella risposta generale e available nello strumento. Usa questa risposta come riferimento attuale, senza assumere quantità, modelli, schemi o prezzi fissi. Filtra la risposta salvata per visualizzare solo web_search.

echo "$NOIMOS_TOOLS_RESPONSE" | jq \
  '.data.tools[] | select(.name == "web_search") | {
    name,
    description,
    available,
    inputSchema,
    example,
    models,
    price
  }'

5. Ottenere un preventivo prima dell’esecuzione

Invia nome e argomenti dello strumento per ricevere versione prezzi e prenotazione massima. Questo non avvia attività a pagamento.

NOIMOS_QUOTE_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/quote" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "tool": "web_search",
    "arguments": {
      "query": "content marketing trends",
      "count": 5
    }
  }')

echo "$NOIMOS_QUOTE_RESPONSE" | jq

Il preventivo restituisce priceVersion e maximumChargeMicros necessari per l’esecuzione. Riutilizzali senza modificarli o calcolarli. maximumChargeMicros è un intero in milionesimi di USD: 1 USD equivale a 1,000,000 micros.

{
  "data": {
    "tool": "web_search",
    "priceVersion": "...",
    "currency": "usd",
    "minimumChargeMicros": 0,
    "maximumChargeMicros": 0,
    "expiresAt": "..."
  }
}

Gli importi sopra illustrano solo il formato. Il prossimo passaggio legge i valori reali dalla risposta salvata.

6. Eseguire la richiesta preventivata

Mantieni strumento e argomenti del preventivo, aggiungendo versione prezzi e prenotazione massima. Includi una chiave di idempotenza per identificare la richiesta logica.

export NOIMOS_PRICE_VERSION=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.priceVersion')
export NOIMOS_MAXIMUM_CHARGE_MICROS=$(echo "$NOIMOS_QUOTE_RESPONSE" | jq -r '.data.maximumChargeMicros')
export NOIMOS_IDEMPOTENCY_KEY=$(uuidgen)

NOIMOS_EXECUTION_RESPONSE=$(curl --fail-with-body \
  "$NOIMOS_PLATFORM_API_URL/tools/web_search" \
  -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $NOIMOS_IDEMPOTENCY_KEY" \
  --data "$(jq -n \
    --arg priceVersion "$NOIMOS_PRICE_VERSION" \
    --argjson maximumChargeMicros "$NOIMOS_MAXIMUM_CHARGE_MICROS" \
    '{
      tool: "web_search",
      arguments: {
        query: "content marketing trends",
        count: 5
      },
      priceVersion: $priceVersion,
      maximumChargeMicros: $maximumChargeMicros
    }')")

echo "$NOIMOS_EXECUTION_RESPONSE" | jq
export NOIMOS_EXECUTION_ID=$(echo "$NOIMOS_EXECUTION_RESPONSE" | jq -r '.data.id')

L’esempio riusa il preventivo del passaggio 5 e genera una chiave con uuidgen. L’accettazione restituisce HTTP 202 e un ID di esecuzione.

{
  "data": {
    "id": "EXECUTION_ID",
    "tool": "web_search",
    "status": "queued",
    "reservedMicros": 0,
    "chargedMicros": 0
  }
}

La risposta include anche versione prezzi, output, errori e date. chargedMicros: 0 durante l’elaborazione non significa che il costo sia stato definitivamente azzerato.

7. Interrogare lo stesso ID di esecuzione

Usa l’ID salvato al passaggio 6 e interrogalo a intervalli di almeno cinque secondi fino al completamento.

while true; do
  NOIMOS_STATUS_RESPONSE=$(curl --fail-with-body \
    "$NOIMOS_PLATFORM_API_URL/tools/executions/$NOIMOS_EXECUTION_ID" \
    -H "Authorization: Bearer $NOIMOS_PLATFORM_API_KEY")

  echo "$NOIMOS_STATUS_RESPONSE" | jq
  NOIMOS_STATUS=$(echo "$NOIMOS_STATUS_RESPONSE" | jq -r '.data.status')

  case "$NOIMOS_STATUS" in
    succeeded|failed|cancelled|needs_review) break ;;
  esac

  sleep 5
done

queued, running e waiting indicano elaborazione in corso. Con succeeded, leggi output e chargedMicros. Consulta Gestire esecuzione e fatturazione per altri stati.

Se la risposta è sconosciuta, non reinviare con una nuova chiave di idempotenza. Stesso corpo e stessa chiave recuperano l’esecuzione già accettata.

Pagine correlate

Prosegui con le pagine pertinenti:

Autenticare le richieste: autorizzazioni e conservazione delle chiavi
Gestire esecuzione e fatturazione: attività lunghe, tentativi successivi e addebiti
Riferimento API: endpoint, stati e limiti
Documentazione Developer Platform: esempi aggiornati

API

CLI

Server MCP

Primi passi

Panoramica

Prerequisiti

Eseguire l’API

1. Creare una chiave in Developer Platform

2. Impostare chiave e URL di base

3. Verificare il progetto della chiave

4. Consultare gli strumenti disponibili

5. Ottenere un preventivo prima dell’esecuzione

6. Eseguire la richiesta preventivata

7. Interrogare lo stesso ID di esecuzione

Pagine correlate

​Panoramica

​Prerequisiti

​Eseguire l’API

​1. Creare una chiave in Developer Platform

​2. Impostare chiave e URL di base

​3. Verificare il progetto della chiave

​4. Consultare gli strumenti disponibili

​5. Ottenere un preventivo prima dell’esecuzione

​6. Eseguire la richiesta preventivata

​7. Interrogare lo stesso ID di esecuzione

​Pagine correlate

Panoramica

Prerequisiti

Eseguire l’API

1. Creare una chiave in Developer Platform

2. Impostare chiave e URL di base

3. Verificare il progetto della chiave

4. Consultare gli strumenti disponibili

5. Ottenere un preventivo prima dell’esecuzione

6. Eseguire la richiesta preventivata

7. Interrogare lo stesso ID di esecuzione

Pagine correlate