Referência da API do Jenova Agent

URL Base: https://api.jenova.ai/v1

Autenticação: Token Bearer no cabeçalho Authorization

Sumário

• Visão Geral
• Início Rápido
• Conceitos Fundamentais
• Autenticação
• Pontos de Extremidade da API
  • Mensagens
  • Sessões
  • Operações
  • Créditos
  • Agentes
  • Modelos
  • Documentação
• Transmissão (SSE)
• Integração com Servidor MCP
• Faturamento
• Limites de Taxa
• Tratamento de Erros
• Paginação
• Localização
• Privacidade e Dados
• Suporte

Visão Geral

Construa e execute agentes de IA prontos para produção sem precisar montar a infraestrutura subjacente você mesmo. A API do Jenova Agent reúne todas as capacidades essenciais em um único serviço gerenciado:

A Pilha Completa de Agentes

• Orquestração de Agentes: Uma camada de orquestração unificada coordena modelos, ferramentas, memória e recuperação em fluxos de trabalho complexos.
• Memória e Contexto: Memória e contexto de conversação ilimitados integrados a cada sessão. Nenhum gerenciamento de estado externo é necessário.
• Ferramentas e MCP: Integrações ilimitadas de ferramentas, com ferramentas nativas da plataforma e qualquer servidor MCP remoto, prontas para uso imediato.
• Use Qualquer Modelo: Potencialize seus agentes com modelos da OpenAI, Anthropic, Google, xAI, Qwen e outros por meio de uma única integração.
• Armazenamento Totalmente Gerenciado: Bancos de dados relacionais e vetoriais gerenciados com RAG integrado. Nenhuma infraestrutura para provisionar ou escalar.
• Nível de Produção: Utilizado por centenas de milhares de usuários. Infraestrutura totalmente gerenciada, APIs estáveis, construído para tráfego de produção.

Início Rápido

1. Obtenha Sua Chave de API

Gere uma chave de API no painel do desenvolvedor em www.jenova.ai/platform. As chaves seguem o formato jnv_sk_* e são passadas como tokens Bearer.

2. Escolha ou Crie um Agente

Escolha um agente pré-construído na plataforma ou crie um agente personalizado no painel com instruções, configurações de modelo, arquivos de base de conhecimento, ferramentas e servidores MCP.

3. Envie Sua Primeira Mensagem

Crie uma sessão e envie uma mensagem em uma única chamada:

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "What can you help me with?"
  }'

A resposta é transmitida de volta como Server-Sent Events:

event: stream_started
data: {"session_id":"ses_xyz789","run_id":"run_abc123","agent":"my-support-agent"}

event: stream_delta
data: {"session_id":"ses_xyz789","run_id":"run_abc123","chunk_content":"I can help you with ","seq":1}

event: stream_ended
data: {"session_id":"ses_xyz789","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Capture o session_id de stream_started para solicitações subsequentes. Para respostas JSON síncronas, consulte Enviar Mensagem.

Conceitos Fundamentais

Agente

Um agente de IA com o qual você interage por meio da API. Cada agente possui um slug único (por exemplo, my-support-agent) usado como o valor de agent nas chamadas da API.

• Pré-construído: Selecione entre os agentes existentes na plataforma.
• Personalizado: Configure o seu próprio no painel com instruções, modelo, base de conhecimento, ferramentas e servidores MCP.

Sessão

Uma linha de conversação independente entre um usuário final e um agente.

• Identificador: ID com prefixo (por exemplo, ses_abc123)
• Escopo: Podem existir múltiplas sessões para o mesmo agente e usuário final, cada uma com estado de conversação independente
• Ciclo de vida: As sessões persistem indefinidamente até serem excluídas por meio da API. Para tarefas pontuais sem armazenamento, use POST /messages com ephemeral: true
• Isolamento de plataforma: As sessões da API são separadas das conversas no aplicativo web do Jenova. Usuários finais, histórico de sessões e faturamento são independentes entre a API e o aplicativo web.

Mensagem

Uma única entrada no histórico de conversação de uma sessão, retornada pelos pontos de extremidade de Mensagens. Cada mensagem inclui um objeto from estruturado com type ("user" ou "agent") e name, além de um type de mensagem:

• external - uma mensagem de conversação destinada a ser exibida como conteúdo de chat.
• internal - uma mensagem opcional que representa etapas de trabalho do agente durante uma execução, como chamadas de ferramentas ou recuperação.

Execução

Uma única execução de agente criada ao enviar uma mensagem. Uma execução possui um run_id, pode transmitir eventos enquanto estiver ativa e produz uma ou mais mensagens concluídas. Cada sessão pode ter apenas uma execução ativa por vez.

Usuário Final

O campo user associa sessões a um usuário final em seu aplicativo. Use um ID opaco estável, como seu ID de usuário interno ou UUID. Evite e-mails ou outras informações pessoais identificáveis, a menos que seu aplicativo exija isso. Sessões criadas com o mesmo valor de user são agrupadas, permitindo a listagem de sessões por usuário.

Se user for omitido, a sessão fica associada à sua conta de desenvolvedor e não poderá ser filtrada por usuário final posteriormente. Informe user em produção.

Para solicitações de sessões existentes, user é uma proteção de propriedade opcional. Se você o fornecer, ele deve corresponder ao valor de user usado quando a sessão foi criada; caso contrário, a API retorna 404 session_not_owned. Envie-o como parâmetro de consulta em solicitações GET e DELETE, e no corpo JSON em solicitações POST e PATCH.

Autenticação

Autentique cada solicitação com um token Bearer no cabeçalho Authorization:

Authorization: Bearer jnv_sk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

As chaves de API são geradas no painel do desenvolvedor.

User-Agent é opcional. Os SDKs podem defini-lo para fins de diagnóstico, mas a API não exige isso.

Formato da chave: As chaves começam com o prefixo jnv_sk_ seguido por uma string aleatória codificada em base62.

Limites: Cada conta de desenvolvedor pode ter até 10 chaves de API ativas.

Pontos de Extremidade da API

Mensagens

O envio de mensagens é o caminho principal da API. Use POST /messages para a primeira mensagem; isso cria a sessão e inicia a execução em uma única solicitação. Use POST /sessions/{session_id}/messages ao continuar um session_id já capturado.

Enviar Mensagem

POST /messages

Cria uma sessão persistente e envia a primeira mensagem em uma solicitação atômica única. Defina ephemeral: true para uma solicitação avulsa sem armazenamento, apenas com transmissão, que não armazena histórico de sessão ou mensagens, não retorna ID de sessão e não pode ser continuada.

Corpo da Solicitação

Exemplo - Transmissão (padrão)

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account"
  }'

A resposta é um fluxo SSE (consulte Transmissão (SSE) para o formato dos eventos). Solicitações persistentes incluem o novo session_id; solicitações com ephemeral: true omitem session_id e devem usar transmissão.

Exemplo - JSON (sem transmissão)

curl -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello, I need help with my account",
    "stream": false
  }'

Resposta

As respostas com transmissão emitem os eventos SSE documentados em Transmissão (SSE). As respostas sem transmissão retornam o formato de mensagem JSON mostrado em Continuar Sessão, incluindo stop_reason e usage para a solicitação concluída.

Se uma execução sem transmissão ainda estiver em processamento após 90 segundos, a API retorna 202 Accepted com status: "processing", session_id, run_id e message. A execução continua após a resposta ou a desconexão do cliente; verifique as mensagens da sessão ou use transmissão para fluxos de trabalho mais longos.

Erros

Continuar Sessão

POST /sessions/{session_id}/messages

Envia uma Mensagem para uma Sessão persistente existente e recebe a resposta do agente. As respostas são transmitidas via SSE por padrão; defina stream: false para JSON.

Corpo da Solicitação

Exemplo - Transmissão (padrão)

curl -N -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?"
  }'

Exemplo - JSON (sem transmissão)

curl -X POST https://api.jenova.ai/v1/sessions/ses_abc123/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "How do I reset my password?",
    "stream": false
  }'

Resposta 200 OK

{
  "id": "msg_xyz789",
  "session_id": "ses_abc123",
  "sequence": 4,
  "from": {
    "type": "agent",
    "name": "my-support-agent"
  },
  "type": "external",
  "time": "2026-05-19T10:31:05Z",
  "content": "To reset your password, go to Settings > Security > Change Password...",
  "model": "claude-sonnet-5",
  "files": [],
  "stop_reason": "end_run",
  "usage": {
    "cost": "0.0015"
  }
}

Se a Sessão já tiver uma Execução ativa ou Mensagens na fila, a API retorna JSON 202 Accepted com status: "queued", session_id, run_id e message_id. A Mensagem do usuário é processada pela Execução ativa.

Erros

Idempotência

POST /messages e POST /sessions/{session_id}/messages aceitam um cabeçalho Idempotency-Key opcional. Use uma chave exclusiva para cada envio lógico do usuário para que novas tentativas de rede ou envios duplicados não criem execuções duplicadas.

curl -N -X POST https://api.jenova.ai/v1/messages \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: send-user_12345-2026-05-19T10:30:00Z" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "content": "Hello"
  }'

Sem transmissão: Uma nova tentativa retorna a resposta 200 ou 202 salva com o cabeçalho Idempotent-Replayed: true.

Com transmissão: O stream não é reproduzido novamente. Tentar novamente durante a execução ou após a conclusão retorna um erro de idempotência com o run_id original e, para solicitações persistentes, o session_id. Use GET /sessions/{session_id}/runs/{run_id} para verificar uma execução ativa, ou GET /sessions/{session_id}/messages para buscar os resultados persistidos.

Exemplo de nova tentativa em uma transmissão já concluída:

HTTP/1.1 409 Conflict
Content-Type: application/json

{
  "error": {
    "code": "idempotency_key_reused",
    "message": "This Idempotency-Key has already completed. Streaming responses cannot be replayed; use the returned session_id and run_id to retrieve the result."
  },
  "idempotency": {
    "status": "completed",
    "session_id": "ses_abc123",
    "run_id": "run_abc123"
  }
}

Erros de idempotência

Listar Mensagens

GET /sessions/{session_id}/messages

Retorna uma lista paginada de mensagens de conversa visíveis. A primeira página contém as mensagens mais recentes; dentro de cada página, as mensagens estão em ordem cronológica (as mais antigas primeiro). sequence é um número de ordenação estável dentro da sessão.

Parâmetros de Consulta

Exemplo

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=50" \
  -H "Authorization: Bearer jnv_sk_xxx"

Resposta 200 OK

{
  "items": [
    {
      "id": "msg_002",
      "session_id": "ses_abc123",
      "sequence": 4,
      "from": {
        "type": "agent",
        "name": "my-support-agent"
      },
      "type": "external",
      "time": "2026-05-19T10:31:05Z",
      "content": "To reset your password, go to Settings > Security...",
      "model": "claude-sonnet-5",
      "files": []
    }
  ],
  "next_cursor": "",
  "has_more": false
}

Objeto de mensagem

Objeto de arquivo

Erros

Obter Mensagem

GET /sessions/{session_id}/messages/{message_id}

Recupera uma única mensagem visível pelo ID.

Resposta 200 OK

Retorna um único objeto de mensagem com a mesma estrutura da resposta de listagem.

Erros

Anexos de Arquivo

Informe URLs em HTTPS publicamente acessíveis no campo file_urls.

Formatos suportados

• Imagens: JPG, JPEG, PNG, WebP
• Documentos: PDF, DOCX, XLSX, PPTX, TXT, CSV, RTF, MD, HTML, XML, JSON, LOG
• Código: JS, TS, TSX, JSX, PY, Java, Go, C, CPP, H, HPP, CS, RB, PHP, RS, Swift, KT, Scala, SQL, CSS, YAML, YML

Ao listar mensagens, os arquivos anexados aparecem no array files da mensagem.

Sessões

Sessões são conversas persistentes entre um usuário final e um agente. A maioria das integrações pode criá-las implicitamente com POST /messages.

Criar Sessão

POST /sessions

Cria uma sessão persistente vazia vinculada a um agente específico. Use isso quando precisar de um ID de sessão antes da primeira mensagem; caso contrário, prefira POST /messages.

Nota: ephemeral não é aceito em POST /sessions; use POST /messages com ephemeral: true para solicitações pontuais sem armazenamento.

Corpo da Solicitação

Exemplo

curl -X POST https://api.jenova.ai/v1/sessions \
  -H "Authorization: Bearer jnv_sk_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "my-support-agent",
    "user": "user_12345",
    "session_name": "Billing inquiry"
  }'

Resposta 201 Created

{
  "id": "ses_abc123",
  "session_name": "Billing inquiry",
  "agent": "my-support-agent",
  "user": "user_12345",
  "model": "claude-sonnet-5",
  "created_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:00Z"
}

Erros

Listar Sessões

GET /sessions

Retorna uma lista paginada de suas sessões, ordenadas pela mais recentemente atualizada.

Parâmetros de Consulta

Exemplo

curl "https://api.jenova.ai/v1/sessions?user=user_12345&limit=10" \
  -H "Authorization: Bearer jnv_sk_xxx"

Resposta 200 OK

{
  "items": [
    {
      "id": "ses_abc123",
      "session_name": "Billing inquiry",
      "agent": "my-support-agent",
      "user": "user_12345",
      "model": "claude-sonnet-5",
      "created_at": "2026-05-19T10:30:00Z",
      "updated_at": "2026-05-19T11:15:00Z"
    }
  ],
  "next_cursor": "eyJ2IjoxLCJrIjoiY3VyXzAxIn0",
  "has_more": true
}

Erros

Obter Sessão

GET /sessions/{session_id}

Recupera uma única sessão pelo ID.

Resposta 200 OK

Retorna um objeto de sessão com a mesma estrutura da resposta de criação.

Erros

Renomear Sessão

PATCH /sessions/{session_id}

Atualiza o nome de exibição de uma sessão.

Corpo da Solicitação

Resposta 200 OK

Retorna o objeto de sessão atualizado.

Erros

Excluir Sessão

DELETE /sessions/{session_id}

Exclui permanentemente uma sessão e todas as suas mensagens. A sessão não pode ter uma execução ativa.

Resposta 204 No Content

Erros

Operações

Esses pontos de extremidade são controles de recuperação e edição para sessões persistentes. A maioria das integrações precisa apenas de Cancelar; use as demais operações quando você quiser intencionalmente alterar ou recuperar o estado da sessão. Todas as operações suportam a proteção de propriedade opcional user descrita em Usuário Final.

Cancelar Execução Ativa

POST /sessions/{session_id}/cancel

Cancela a execução do agente em andamento atualmente. Isso não exclui as mensagens que já foram concluídas antes do cancelamento.

Corpo da Solicitação

Resposta 204 No Content

Erros

Desfazer Execução Ativa

POST /sessions/{session_id}/undo

Cancela a execução ativa, espera que ela seja interrompida e, em seguida, remove todas as mensagens que ela já havia adicionado. Nenhuma saída adicional é persistida após a solicitação de desfazer.

Corpo da Solicitação

Resposta 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "deleted": ["msg_002", "msg_001"]
}

Se a execução for cancelada antes de qualquer mensagem ser concluída, deleted é um array vazio.

Erros

Excluir Mensagens Recentes

POST /sessions/{session_id}/messages/delete

Remove as N mensagens mais recentes de uma sessão inativa. A sessão não deve ter uma execução ativa.

Corpo da Solicitação

Resposta 200 OK

{
  "deleted": ["msg_002", "msg_001"]
}

Erros

Bifurcar Sessão

POST /sessions/{session_id}/fork

Cria uma nova sessão copiando a sessão de origem até uma mensagem específica. A sessão de origem não deve ter uma execução ativa.

Corpo da Solicitação

Resposta 201 Created

Retorna o objeto de sessão recém-criado com a mesma estrutura da criação de sessão.

Erros

Obter Status da Execução

GET /sessions/{session_id}/runs/{run_id}

Retorna o estado atual de uma execução ativa. Use este endpoint após uma conexão SSE interrompida ou uma resposta de idempotência que retornou um run_id. Após a conclusão de uma execução, obtenha os resultados com GET /sessions/{session_id}/messages.

Resposta 200 OK

{
  "session_id": "ses_abc123",
  "run_id": "run_abc123",
  "status": "streaming",
  "started_at": "2026-05-19T10:30:00Z",
  "updated_at": "2026-05-19T10:30:06Z",
  "content": "Partial visible response text so far"
}

A resposta também pode incluir dicas de progresso recentes enquanto a execução estiver ativa.

Erros

Créditos

Obter Saldo

GET /credits/balance

Retorna seu saldo de créditos atual.

Resposta 200 OK

{
  "balance": "123.45"
}

Agentes

Crie e edite agentes personalizados no painel. O suporte da API para criação e edição de agentes chegará em breve.

Fluxos de trabalho agendados/em segundo plano não são atualmente compatíveis através da API. O suporte chegará em breve.

Listar Agentes

GET /agents

Retorna os agentes disponíveis para sua chave de API. Use o valor agent ao criar sessões ou enviar mensagens.

Resposta 200 OK

{
  "agents": [
    {
      "agent": "jenova",
      "display_name": "Jenova",
      "description": "General-purpose Jenova agent"
    },
    {
      "agent": "my-support-agent",
      "display_name": "Support Agent",
      "description": "Answers customer questions"
    }
  ]
}

Modelos

Listar Modelos

GET /models

Retorna todos os Modelos disponíveis para uso no Campo model ao enviar mensagens.

Resposta 200 OK

{
  "models": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "thinking_variant": "claude-opus-4-8-thinking"
    },
    {
      "id": "claude-opus-4-8-thinking",
      "name": "Claude Opus 4.8 (Thinking)"
    },
    {
      "id": "kimi-k2.6",
      "name": "Kimi K2.6",
      "thinking_variant": "kimi-k2.6-thinking"
    }
  ]
}

Modelos com um thinking_variant suportam raciocínio estendido. Use o ID da variante diretamente no Campo model para habilitá-lo.

Se nenhum model for especificado ao enviar uma Mensagem, o Modelo padrão do Agente é utilizado.

Documentação

GET /docs?lang=en
GET /doc?lang=en

Retorna esta referência em Markdown. Use lang para selecionar o idioma.

Transmissão (SSE)

Quando stream é omitido ou é true (o padrão), as respostas de Mensagem são entregues como Server-Sent Events. Use os Eventos message_completed para identificar Mensagens prontas para serem buscadas ou renderizadas.

Tempo Limite: as conexões SSE permanecem abertas por até 60 minutos. Solicitações sem transmissão aguardam até 90 segundos e, em seguida, retornam 202 Accepted enquanto a Execução continua.

Cabeçalhos de Conexão

A resposta SSE define estes cabeçalhos:

Content-Type: text/event-stream
Cache-Control: no-cache
Connection: keep-alive
X-Accel-Buffering: no
X-Run-Id: run_abc123

X-Run-Id está disponível antes do primeiro Evento SSE.

Reconexão e Recuperação

Os fluxos SSE não são reproduzidos novamente. Se a conexão cair, use o session_id e o run_id capturados para recuperar o estado:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/runs/run_abc123" \
  -H "Authorization: Bearer jnv_sk_xxx"

Se a Execução ainda estiver ativa, isso retorna o status atual, o texto parcial e o progresso recente. Se retornar 404 not_found, a Execução não está mais ativa; busque as Mensagens da Sessão para reconciliar a saída concluída:

curl "https://api.jenova.ai/v1/sessions/ses_abc123/messages?limit=20" \
  -H "Authorization: Bearer jnv_sk_xxx"

Formato do Quadro

Cada quadro SSE segue o formato padrão:

event: <event_type>
data: <json_payload>

Duas quebras de linha encerram cada quadro.

Tipos de Evento

Os streams incluem eventos de ciclo de vida, delta de texto, pensamento, progresso, aviso, conclusão de mensagem, conexão MCP, erro, final e ping. Alguns tipos de evento são enviados apenas quando relevantes.

Para solicitações efêmeras (ephemeral: true), todo evento SSE omite session_id. Use run_id apenas para correlacionar eventos dentro dessa única transmissão.

Para a reconciliação final em solicitações persistentes, aguarde o evento stream_ended e, em seguida, chame List Messages.

Campos comuns em eventos com escopo de execução:

stream_started

Enviado uma vez quando a execução é iniciada.

stream_delta

Enviado repetidamente à medida que o agente gera o texto de resposta visível. Concatene os valores de chunk_content na ordem de seq para construir a resposta transmitida.

event: stream_delta
data: {"session_id":"ses_abc123","run_id":"run_abc123","chunk_content":"To reset your ","seq":1}

stream_thinking

Enviado repetidamente enquanto o agente emite a saída de pensamento. Use-o para um indicador de pensamento separado ou uma visualização de rastreamento; não o concatene ao texto final da resposta.

stream_progress

Relata atividade visível ao usuário durante a geração, como ler um documento, pesquisar na web ou aguardar uma ação do usuário. Esses eventos destinam-se a uma exibição temporária na interface; ignore campos desconhecidos. Use mensagens concluídas como o histórico de mensagens autoritativo.

Avançado: as solicitações de mensagem aceitam include_progress: false para omitir apenas stream_progress. Eventos de ciclo de vida, ping, message_completed, erros e eventos terminais ainda são enviados quando relevantes.

Alguns eventos de progresso podem incluir url, file_name ou server_name como dicas de exibição opcionais.

message_completed

Enviado sempre que uma mensagem é concluída e está pronta para ser buscada ou renderizada.

Este é um marcador de limite, não o objeto completo da mensagem. Busque a mensagem se precisar do conteúdo ou dos metadados.

event: message_completed
data: {"session_id":"ses_abc123","run_id":"run_abc123","message_id":"msg_abc123","sequence":4,"from":{"type":"agent","name":"Jenova"},"type":"external"}

mcp_connection

Enviado quando o agente precisa que o usuário final conecte ou autorize um ou mais servidores MCP antes de continuar. Este evento está disponível apenas no modo streaming.

mcp_connection_resolved

Enviado quando a ação do usuário de conexão MCP foi resolvida ou expirou.

Nenhum campo adicional além dos campos comuns com escopo de execução.

warning

Enviado para avisos não fatais durante uma execução.

stream_error

Enviado quando uma execução falha. Um evento final stream_ended pode ser enviado a seguir com success:false e stop_reason:"error".

stream_ended

Enviado uma vez quando a execução termina. Este é o evento final do stream.

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":true,"stop_reason":"end_run","usage":{"cost":"0.0032"}}

Exemplo de falha:

event: stream_ended
data: {"session_id":"ses_abc123","run_id":"run_abc123","success":false,"stop_reason":"user_cancelled","usage":{"cost":"0.0012"}}

ping

Quadros de manutenção de conexão enviados a cada 15 segundos para evitar tempos limite de proxy/CDN. Ignore-os no seu cliente.

Integração com Servidor MCP

Conecte seus agentes a ferramentas externas por meio do Model Context Protocol (MCP):

• Servidores MCP gerenciados pela Jenova: servidores hospedados pela Jenova para busca, recuperação de conteúdo, geração de documentos e outras capacidades integradas
• Servidores MCP remotos: outros servidores MCP remotos configurados para seu Agente

Os servidores MCP devem ser configurados no painel ao criar ou editar seu Agente. Para usar seu próprio servidor MCP, adicione-o a um Agente personalizado e, em seguida, chame esse Agente pela API. A API executa as Ferramentas habilitadas na configuração do Agente; nenhuma configuração adicional é necessária nas solicitações da API.

Quando um Agente usa Ferramentas MCP durante uma resposta, Eventos de progresso são enviados no stream conforme ocorrem:

event: stream_progress
data: {"session_id":"ses_...","run_id":"run_...","state":"running","label":"Searching Google"}

Se o agente precisar que o usuário final conecte ou autorize um servidor MCP durante a execução, as respostas em streaming podem incluir os eventos mcp_connection e mcp_connection_resolved. Apresente a lista de servidores de conexão ao usuário final e abra a auth_url fornecida quando presente. Mantenha o stream SSE aberto enquanto o usuário conecta ou autoriza o servidor.

Após a autorização, a Jenova armazena o token, a janela de autorização exibe uma página de conclusão, e a mesma Execução continua automaticamente. O Usuário Final não precisa reenviar a Mensagem.

Se o usuário final não conectar, autorizar, ignorar ou silenciar antes de user_action_deadline_unix, a execução termina com stop_reason:"user_action_timeout". Você também pode cancelar a execução ativa com POST /sessions/{session_id}/cancel.

Armazene a auth_url no lado do cliente. Se o cliente se desconectar durante a autorização, a URL permanece válida até user_action_deadline_unix. Para solicitações persistentes, reconecte-se com Get Run Status ou busque as mensagens após a execução terminar.

Solicitações sem streaming (stream: false) não oferecem suporte a ações do usuário de conexão MCP; use streaming para agentes que possam precisar dessa interação.

Ignorar conexão MCP

POST /sessions/{session_id}/mcp/connection/skip

Dispensa uma ação do usuário de conexão MCP pendente e permite que a execução continue sem essa conexão.

Para silenciar futuros prompts de conexão para um servidor para o mesmo usuário de API, inclua mcp_server_id e mute. Os valores compatíveis são 24h e forever.

Corpo da Solicitação

Resposta 204 No Content

O stream emite mcp_connection_resolved, e então a execução continua com o mesmo run_id.

Erros

Faturamento

Todos os custos são deduzidos do seu saldo de Créditos de desenvolvedor. Veja o uso e adicione Créditos em www.jenova.ai/platform.

Preços

O custo da Mensagem depende de:

• Modelo - Modelos diferentes têm custos por token diferentes
• Tamanho do contexto - Sessões mais longas consomem mais tokens de entrada por solicitação
• Complexidade do fluxo de trabalho - fluxos de trabalho mais longos e uso intenso de Ferramentas (busca na web, geração de arquivos, análise de documentos) aumentam o consumo total de tokens

O custo real é retornado como stream_ended.usage.cost para solicitações em Transmissão e usage.cost para solicitações JSON não transmitidas.

Retenções de Créditos

Cada nova Execução de Mensagem coloca uma retenção de $0,50 no seu saldo de Créditos antes do início da execução. Isso reserva fundos para a Execução. Mensagens de acompanhamento em fila em uma Execução ativa não criam retenções adicionais; o uso da Execução ativa é verificado em relação ao seu saldo restante.

Quando a Execução é concluída, a retenção é liquidada pelo custo real e a diferença é liberada. Execuções canceladas ou com falha são cobradas apenas pelo uso já incorrido. Se uma solicitação falhar antes de chegar ao Modelo, toda a retenção é liberada.

Isso significa que seu saldo disponível pode parecer temporariamente menor durante solicitações em andamento. Você precisa de pelo menos $0,50 em saldo disponível para enviar uma Mensagem para uma Sessão existente ou para enviar uma Mensagem efêmera. Uma primeira solicitação persistente POST /messages cria uma Sessão e requer pelo menos $0,51 para cobrir a retenção da Mensagem mais a taxa de criação de Sessão.

Limites de Taxa

Toda conta de desenvolvedor está sujeita a três dimensões de Limite de Taxa:

Solicitações GET e HEAD não consomem slots concorrentes. cancel, undo e mcp/connection/skip também não consomem slots concorrentes, portanto essas operações permanecem disponíveis quando todos os slots estão em uso. Essas solicitações ainda contam para RPM e RPD.

Cabeçalhos de Resposta

As respostas autenticadas da API incluem cabeçalhos de limite de taxa:

Quando um limite é excedido, a API retorna 429 Too Many Requests:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please retry after 12 seconds."
  }
}

Tratamento de Erros

Erros HTTP imediatos e erros de execução sem transmissão seguem um envelope consistente:

{
  "error": {
    "code": "error_code_string",
    "message": "Human-readable description"
  }
}

As mensagens de erro são localizadas com base no parâmetro lang (veja Localização).

Erros de execução em transmissão são entregues como Eventos stream_error. Uma execução com falha ainda pode enviar um Evento final stream_ended com success:false e stop_reason definido. Erros de execução sem transmissão também podem incluir um objeto usage de nível superior quando os dados de custo estiverem disponíveis.

Erros específicos de cada ponto de extremidade são documentados junto à descrição de cada ponto de extremidade.

Erros de Execução Após o Início

Erros de execução surgem depois que uma execução de mensagem já foi iniciada. No modo de transmissão, eles aparecem como Eventos stream_error e podem ser seguidos por stream_ended com success:false. No modo sem transmissão, eles são retornados como uma resposta de erro em JSON com o Código de Status HTTP abaixo.

Paginação

Os pontos de extremidade de listagem usam paginação baseada em cursor:

{
  "items": [],
  "next_cursor": "eyJ2IjoxLCJrIjoiY3VyXzAyIn0",
  "has_more": true
}

Passe next_cursor como o parâmetro de consulta cursor para buscar a próxima página. Quando has_more for false, não há mais resultados.

Localização

Todos os pontos de extremidade aceitam um parâmetro de consulta opcional lang para controlar o idioma das mensagens de erro e de qualquer conteúdo localizado.

Você pode anexar ?lang=xx a qualquer URL de solicitação:

POST /sessions?lang=zh
GET /sessions/ses_abc123/messages?lang=ja

Idiomas suportados: en, zh, ja, ko, es, fr, de, it, pt, ru, id, th, vi

Privacidade e Dados

A Jenova não usa prompts da API, saídas, histórico de conversas, arquivos enviados, instruções de Agentes ou Bases de Conhecimento para treinar os Modelos da Jenova.

Para provedores de Modelos de terceiros, a Jenova utiliza canais comerciais de API, configurações de conta, compromissos contratuais ou opções de exclusão destinados a impedir que o conteúdo do cliente seja usado para treinar os Modelos do provedor.

A Jenova armazena e processa dados da API usando infraestrutura dos EUA. Provedores terceiros podem processar dados em outras jurisdições, conforme descrito na Política de Privacidade e nos Termos de Uso.

Para mais detalhes, consulte os Termos de Uso, a Política de Privacidade e a Política de Uso.

Suporte

• Painel: www.jenova.ai/platform
• E-mail: [email protected]