Primeros pasos

Descripción general

Este ejemplo usa web_search para preparar una clave, solicitar un presupuesto gratuito, ejecutar y obtener el resultado. Solo necesitas un shell compatible con Bash y cURL, sin un SDK específico.

Requisitos previos

Prepara estos cinco elementos:

Una cuenta de NoimosAI con acceso a Developer Platform
Un proyecto de Developer Platform con acceso API habilitado
Una clave de desarrollador con prefijo nmp_ y los permisos necesarios
Un shell compatible con Bash
cURL, jq y uuidgen

Para ejecutar trabajo de pago, revisa también el saldo prepagado en USD y los límites mensuales del proyecto. Consulta los permisos en Autenticar solicitudes. Si no aparece ningún proyecto accesible, pide a un OWNER o ADMIN de la organización que cree uno o te añada. Las claves se crean dentro de un proyecto al que perteneces.

Ejecutar la API

Sigue estos siete pasos para tu primera ejecución.

1. Crear una clave en Developer Platform

Un ADMIN o DEVELOPER del proyecto puede crear una clave en Developer Platform:

Inicia sesión y selecciona el proyecto.
Abre Claves API y elige Crear nueva clave.
Indica un nombre descriptivo, vencimiento y permisos; crea la clave.
Guarda la clave secreta en un lugar seguro: solo se muestra una vez.

Este ejemplo requiere project:read, tools:read, tools:execute y executions:read. Para otros usos, concede solo los permisos necesarios.

2. Configurar la clave y la URL base

Guarda la clave y la URL base en variables de entorno para evitar escribir secretos directamente en el historial o código fuente.

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

La clave solo se muestra una vez al crearla. No la guardes en Git, documentos compartidos ni JavaScript del cliente.

3. Comprobar el proyecto de la clave

Comprueba primero que la clave corresponde al proyecto previsto de Developer Platform.

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

La respuesta correcta incluye ID de organización, ID y nombre del proyecto en data. Si no es el proyecto esperado, revisa la clave antes de ejecutar trabajo de pago.

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

4. Consultar las herramientas disponibles

Obtén nombres, descripciones, esquemas, ejemplos, disponibilidad y precios actuales.

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

echo "$NOIMOS_TOOLS_RESPONSE" | jq

Revisa executionEnabled en la respuesta general y available en la herramienta. Usa la respuesta como referencia actual, sin asumir cantidades, modelos, esquemas o precios fijos. Filtra la respuesta guardada para consultar solo web_search.

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

5. Solicitar un presupuesto antes de ejecutar

Envía el nombre de herramienta y sus argumentos para obtener la versión de precios y la reserva máxima. Esto no inicia trabajo de pago.

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

El presupuesto devuelve priceVersion y maximumChargeMicros, necesarios para ejecutar. Reutilízalos sin modificarlos ni calcularlos. maximumChargeMicros es un entero en millonésimas de USD: 1 USD equivale a 1,000,000 micros.

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

Los importes anteriores solo ilustran el formato. El siguiente paso obtiene los valores reales de la respuesta guardada.

6. Ejecutar la solicitud presupuestada

Usa la misma herramienta y argumentos y añade la versión de precios y reserva máxima recibidas. Incluye una clave de idempotencia que identifique la solicitud lógica.

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')

Este ejemplo reutiliza el presupuesto del paso 5 y genera una clave con uuidgen. La aceptación devuelve HTTP 202 y un ID de ejecución.

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

También se devuelven versión de precios, salida, errores y fechas. chargedMicros: 0 durante el proceso no significa que se haya liquidado como gratuito.

7. Consultar el mismo ID de ejecución

Usa el ID guardado en el paso 6 y consulta a intervalos de al menos cinco segundos hasta que termine.

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 y waiting indican procesamiento pendiente. Con succeeded, lee output y chargedMicros. Consulta otros estados en Gestionar ejecución y facturación.

Si desconoces la respuesta, no reenvíes con una nueva clave de idempotencia. El mismo cuerpo y la misma clave permiten recuperar la ejecución ya aceptada.

Páginas relacionadas

Después, consulta las páginas pertinentes:

Autenticar solicitudes: permisos y almacenamiento de claves
Gestionar ejecución y facturación: procesos largos, reintentos y liquidación
Referencia de la API: endpoints, estados y límites
Documentación de Developer Platform: ejemplos actuales

API

CLI

Servidor MCP

Primeros pasos

Descripción general

Requisitos previos

Ejecutar la API

1. Crear una clave en Developer Platform

2. Configurar la clave y la URL base

3. Comprobar el proyecto de la clave

4. Consultar las herramientas disponibles

5. Solicitar un presupuesto antes de ejecutar

6. Ejecutar la solicitud presupuestada

7. Consultar el mismo ID de ejecución

Páginas relacionadas

​Descripción general

​Requisitos previos

​Ejecutar la API

​1. Crear una clave en Developer Platform

​2. Configurar la clave y la URL base

​3. Comprobar el proyecto de la clave

​4. Consultar las herramientas disponibles

​5. Solicitar un presupuesto antes de ejecutar

​6. Ejecutar la solicitud presupuestada

​7. Consultar el mismo ID de ejecución

​Páginas relacionadas

Descripción general

Requisitos previos

Ejecutar la API

1. Crear una clave en Developer Platform

2. Configurar la clave y la URL base

3. Comprobar el proyecto de la clave

4. Consultar las herramientas disponibles

5. Solicitar un presupuesto antes de ejecutar

6. Ejecutar la solicitud presupuestada

7. Consultar el mismo ID de ejecución

Páginas relacionadas