Skip to main content
Use a Agent API para passar uma tarefa ao Krea Agent a partir da sua própria aplicação. Requisições e respostas usam campos JSON em camelCase. O Agent trabalha em segundo plano enquanto sua aplicação lê o progresso e os resultados.
O Agent trabalha em segundo plano. Ele não faz perguntas, e as solicitações de confirmação de custo e permissão são aprovadas automaticamente. Inclua todos os requisitos e restrições no seu prompt. Revise a tarefa antes de enviá-la.

Autenticação, acesso e cobrança

Envie Authorization: Bearer KREA_API_KEY em toda requisição para https://api.krea.ai. Chaves de API pessoais, de serviço e legadas usam a autenticação padrão da API pública. Você só pode ler ou continuar sessões que pertencem ao chamador autenticado no workspace autenticado. Conhecer o ID de uma sessão não concede acesso. Arquivos anexados do Krea também precisam estar acessíveis a esse chamador nesse workspace.
Os turnos do Agent usam o saldo de unidades de computação do workspace. Eles não usam o saldo de API. Os direitos do plano do Agent e os limites de mensagens do plano Free continuam valendo. Veja Planos, acesso e créditos do Agent.
Cada resposta inclui uma url onde você pode abrir a sessão no app do Krea com o acesso adequado à conta e ao workspace.

Inicie uma sessão e aguarde o resultado

Primeiro, defina KREA_API_KEY no seu ambiente. Escolha Bash com curl e jq, Python com requests ou Node.js com o fetch nativo ou o SDK do Krea.
1

Envie o primeiro turno

Omita sessionId para criar uma sessão. Salve o sessionId e o runId retornados. A resposta volta imediatamente com status: "running".
2

Aguarde este turno

Passe os dois IDs para wait-for-session. Se timedOut for true, chame novamente com os mesmos IDs. Um tempo limite esgotado não cancela o turno.
3

Leia o resultado

Verifique status quando finished for true. Inspecione text, media e qualquer error, ou abra a url retornada.
Para Python, instale o requests com pip install requests. Para Node.js, use Node.js 22+ e salve o exemplo como example.mjs. O exemplo com SDK requer npm install @krea-ai/sdk e usa requestRaw para chamar os endpoints HTTP. Esses exemplos enviam uma mensagem e aguardam por até cinco minutos. Eles param em erros HTTP e em turnos que falharam ou foram cancelados. Eles nunca repetem um envio automaticamente. Se uma requisição de envio atingir o tempo limite, verifique a sessão no Krea antes de enviar novamente; a primeira requisição pode ter iniciado um turno. Quando o tempo de espera se esgota, o turno continua em segundo plano. Salve os IDs de sessão e de execução exibidos para retomar a espera depois. timeoutSeconds é um inteiro de 1 a 300 e o padrão é 60. Mantenha o tempo limite do seu cliente HTTP maior que a espera solicitada. Sempre passe o runId mais recente ao aguardar após um envio, para que o status final de um turno anterior não seja confundido com o do novo turno.

Ler sem esperar

Use GET /agent/session/{sessionId} para obter um snapshot da sessão atual:
cURL

Continuar a sessão

Depois que o turno terminar, envie outra mensagem com o sessionId dele:
cURL
Uma sessão executa um turno por vez. Enviar outra mensagem enquanto um turno está em execução retorna 409 com code: "conflict".

Entradas e anexos

send-message aceita estes campos. Veja a referência para o enum completo de modelos e os schemas. A url do anexo aceita uma URL HTTP(S) acessível ou um URI autorizado do Krea Files, como file:550e8400-e29b-41d4-a716-446655440000. Os campos opcionais name e contentType são strings sem espaços nas extremidades, não vazias e com até 255 caracteres. Caminhos locais do chamador e IDs file_ da OpenAI não são suportados. Transfira o arquivo real primeiro; um ID no texto do prompt não transfere o conteúdo. O Agent não herda a conversa nem os anexos da sua aplicação. Anexe arquivos de referência que não estejam acessíveis de outra forma. Você não precisa repetir URLs utilizáveis que já estejam no prompt, no contexto existente do Krea ou em arquivos de sessões anteriores.

Resultados da sessão

send-message retorna sessionId, threadId, runId, status (sempre "running") e url. GET /agent/session/{sessionId} e wait-for-session retornam a seguinte visão da sessão. Somente wait-for-session adiciona o campo obrigatório timedOut. Cada item de media pode representar uma geração (jobId e mediaKind opcional: image, video, audio ou 3d), uma mídia rehospedada (url, com mimeType opcional) ou um arquivo do Krea (uri, name, mimeType). Obtenha os detalhes da geração por meio de GET /jobs/{jobId}. Você pode reutilizar o URI de um arquivo do Krea como anexo ou abrir a url da sessão para ver os arquivos. As mídias podem aparecer enquanto o turno ainda está em execução.

Erros

Os erros dos endpoints usam { "error": "...", "code": "...", "allowedModels": ["..."] }. Apenas error é obrigatório. Um turno que falha após o envio aparece como status: "failed" em uma resposta de sessão bem-sucedida.