Skip to main content
Utilize a Agent API para atribuir uma tarefa ao Krea Agent a partir da sua própria aplicação. Os pedidos e as respostas utilizam campos JSON em camelCase. O agente trabalha em segundo plano enquanto a sua aplicação lê o progresso e os resultados.
O agente trabalha em segundo plano. Não faz perguntas, e os pedidos de confirmação de custos e permissões são aprovados automaticamente. Inclua todos os requisitos e restrições no seu prompt. Reveja a tarefa antes de a submeter.

Autenticação, acesso e faturação

Envie Authorization: Bearer KREA_API_KEY em todos os pedidos para https://api.krea.ai. As chaves de API pessoais, de serviço e legadas utilizam a autenticação padrão da API pública. Só pode ler ou continuar sessões que pertençam ao autor da chamada autenticado, na workspace autenticada. Conhecer o ID de uma sessão não concede acesso. Os anexos de ficheiros da Krea também têm de estar acessíveis a esse autor da chamada nessa workspace.
Os turnos do agente utilizam o saldo de unidades de computação da workspace. Não utilizam o saldo de API. Os direitos do plano do agente e os limites de mensagens do plano Free continuam a aplicar-se. Consulte Planos, acesso e créditos do agente.
Cada resposta inclui um url onde pode abrir a sessão na aplicação Krea com o acesso adequado à conta e à workspace.

Iniciar uma sessão e aguardar o resultado

Defina primeiro KREA_API_KEY no seu ambiente. Escolha Bash com curl e jq, Python com requests ou Node.js com o fetch integrado ou o SDK da Krea.
1

Submeter o primeiro turno

Omita sessionId para criar uma sessão. Guarde o sessionId e o runId devolvidos. A resposta é devolvida de imediato com status: "running".
2

Aguardar este turno

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

Ler o resultado

Verifique status quando finished for true. Analise text, media e qualquer error, ou abra o url devolvido.
Para Python, instale requests com pip install requests. Para Node.js, utilize o Node.js 22+ e guarde o exemplo como example.mjs. O exemplo do SDK requer npm install @krea-ai/sdk e utiliza requestRaw para chamar os endpoints HTTP. Estes exemplos submetem uma mensagem e aguardam até cinco minutos. Param perante erros HTTP e turnos falhados ou cancelados. Nunca repetem um envio automaticamente. Se um pedido de envio exceder o tempo limite, verifique a sessão na Krea antes de submeter novamente; o primeiro pedido pode ter iniciado um turno. Quando o tempo de espera disponível se esgota, o turno continua em segundo plano. Guarde os IDs de sessão e de execução apresentados para retomar a espera mais tarde. timeoutSeconds é um número inteiro de 1 a 300 e o valor predefinido é 60. Mantenha o tempo limite do seu cliente HTTP superior à espera pedida. Passe sempre o runId mais recente ao aguardar após um envio, para que o estado terminal de um turno anterior não seja confundido com o do novo turno.

Ler sem aguardar

Utilize GET /agent/session/{sessionId} para obter um instantâneo da sessão atual:
cURL

Continuar a sessão

Depois de o turno terminar, envie outra mensagem com o respetivo sessionId:
cURL
Uma sessão executa um turno de cada vez. Enviar outra mensagem enquanto um turno está em execução devolve 409 com code: "conflict".

Entradas e anexos

send-message aceita estes campos. Consulte a referência para o enum completo de modelos e os esquemas. O url do anexo aceita um 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. Os caminhos locais do autor da chamada e os IDs file_ da OpenAI não são suportados. Transfira primeiro o ficheiro real; um ID no texto do prompt não transfere o seu conteúdo. O agente não herda a conversa nem os anexos da sua aplicação. Anexe os ficheiros de referência que não estejam acessíveis de outra forma. Não precisa de repetir URLs utilizáveis no prompt, contexto existente da Krea nem ficheiros de sessões anteriores.

Resultados da sessão

send-message devolve sessionId, threadId, runId, status (sempre "running") e url. GET /agent/session/{sessionId} e wait-for-session devolvem a seguinte vista da sessão. Apenas wait-for-session acrescenta o campo obrigatório timedOut. Cada item de media pode representar uma geração (jobId e mediaKind opcional: image, video, audio ou 3d), media realojada (url, com mimeType opcional) ou um ficheiro da Krea (uri, name, mimeType). Obtenha os detalhes da geração através de GET /jobs/{jobId}. Pode reutilizar o URI de um ficheiro da Krea como anexo ou abrir o url da sessão para ver os respetivos ficheiros. A media pode aparecer enquanto o turno ainda está em execução.

Erros

Os erros dos endpoints utilizam { "error": "...", "code": "...", "allowedModels": ["..."] }. Apenas error é obrigatório. Um turno que falhe após a submissão aparece, em vez disso, como status: "failed" numa resposta de sessão bem-sucedida.