Primeiros passos

Visão geral

Este exemplo usa web_search para preparar a chave, obter uma cotação gratuita, executar e recuperar o resultado. Basta um shell compatível com Bash e cURL, sem SDK específico.

Pré-requisitos

Prepare estes cinco itens:

Uma conta NoimosAI com acesso à Developer Platform
Um projeto Developer Platform com acesso API habilitado
Uma chave de desenvolvedor com prefixo nmp_ e permissões necessárias
Um shell compatível com Bash
cURL, jq e uuidgen

Para execução paga, verifique também saldo pré-pago em USD e limites mensais do projeto. Veja permissões em Autenticar solicitações. Se nenhum projeto acessível aparecer, peça a um OWNER ou ADMIN da organização para criar um ou adicionar você. Crie chaves dentro de um projeto do qual participa.

Executar a API

Siga estas sete etapas para a primeira execução.

1. Criar uma chave na Developer Platform

Um ADMIN ou DEVELOPER do projeto pode criar uma chave na Developer Platform:

Entre e selecione o projeto.
Abra Chaves API e escolha Criar nova chave.
Defina nome descritivo, validade e permissões, e crie a chave.
Guarde a chave secreta com segurança: ela aparece uma única vez.

Este guia exige project:read, tools:read, tools:execute e executions:read. Para outros usos, conceda apenas as permissões necessárias.

2. Definir chave e URL base

Use variáveis de ambiente para chave e URL base, evitando segredos diretamente no histórico de comandos ou código-fonte.

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

A chave só aparece na criação. Não a salve em Git, documentos compartilhados ou JavaScript do cliente.

3. Verificar o projeto da chave

Primeiro confirme que a chave corresponde ao projeto esperado da Developer Platform.

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

A resposta inclui ID da organização, ID e nome do projeto em data. Se não for o projeto esperado, verifique a chave antes de executar trabalho pago.

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

4. Consultar ferramentas disponíveis

Obtenha nomes, descrições, esquemas, exemplos, disponibilidade e preços atuais.

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

echo "$NOIMOS_TOOLS_RESPONSE" | jq

Verifique executionEnabled na resposta geral e available na ferramenta. Use a resposta como referência atual sem assumir quantidades, modelos, esquemas ou preços fixos. Filtre a resposta salva para consultar apenas web_search.

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

5. Obter uma cotação antes de executar

Envie nome da ferramenta e argumentos para receber versão de preços e reserva máxima. Isso não inicia trabalho 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

A cotação retorna priceVersion e maximumChargeMicros para execução. Reutilize os valores sem alterar ou calcular. maximumChargeMicros é um inteiro em milionésimos de USD: 1 USD equivale a 1,000,000 micros.

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

Os valores acima apenas ilustram o formato. A próxima etapa lê os valores reais da resposta salva.

6. Executar a solicitação cotada

Mantenha ferramenta e argumentos da cotação, adicionando versão de preços e reserva máxima recebidas. Inclua uma chave de idempotência para identificar a solicitação 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')

O exemplo reutiliza a cotação da etapa 5 e gera uma chave com uuidgen. A aceitação retorna HTTP 202 e um ID de execução.

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

A resposta também inclui versão de preços, saída, erros e datas. chargedMicros: 0 durante o processamento não significa que a cobrança final seja gratuita.

7. Consultar o mesmo ID de execução

Use o ID salvo na etapa 6 e consulte a intervalos de pelo menos cinco segundos até concluir.

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 indicam processamento em andamento. Em succeeded, leia output e chargedMicros. Veja outros estados em Gerenciar execução e cobrança.

Se a resposta for desconhecida, não reenvie com outra chave de idempotência. O mesmo corpo e a mesma chave recuperam a execução já aceita.

Páginas relacionadas

Depois, consulte as páginas pertinentes:

Autenticar solicitações: permissões e armazenamento das chaves
Gerenciar execução e cobrança: processos longos, novas tentativas e cobrança
Referência da API: endpoints, estados e limites
Documentação Developer Platform: exemplos atuais

API

CLI

Servidor MCP

Primeiros passos

Visão geral

Pré-requisitos

Executar a API

1. Criar uma chave na Developer Platform

2. Definir chave e URL base

3. Verificar o projeto da chave

4. Consultar ferramentas disponíveis

5. Obter uma cotação antes de executar

6. Executar a solicitação cotada

7. Consultar o mesmo ID de execução

Páginas relacionadas

​Visão geral

​Pré-requisitos

​Executar a API

​1. Criar uma chave na Developer Platform

​2. Definir chave e URL base

​3. Verificar o projeto da chave

​4. Consultar ferramentas disponíveis

​5. Obter uma cotação antes de executar

​6. Executar a solicitação cotada

​7. Consultar o mesmo ID de execução

​Páginas relacionadas

Visão geral

Pré-requisitos

Executar a API

1. Criar uma chave na Developer Platform

2. Definir chave e URL base

3. Verificar o projeto da chave

4. Consultar ferramentas disponíveis

5. Obter uma cotação antes de executar

6. Executar a solicitação cotada

7. Consultar o mesmo ID de execução

Páginas relacionadas