SDK Orka: Governança de agentes em uma linha de código

Hoje publicamos o SDK oficial da Orka em dois ecossistemas: orkaia no PyPI e orkaia-js no npm. O objetivo é simples — qualquer função de agente existente pode ter governança completa adicionada com uma linha.

Instalação

# Python
pip install orkaia

# TypeScript / Node.js
npm install orkaia-js

Como funciona

O SDK usa o padrão decorator. Você inicializa com sua API key e envolve a função do agente com @orka.guard:

import orka

orka.init(api_key="orka_sua_chave")

@orka.guard(agent_id="uuid-do-agente", task_type="transferencia", risk="HIGH")
def transferir(valor: float, destino: str) -> dict:
    return api_pagamento.transferir(valor, destino)

A partir daí, cada chamada passa por três etapas transparentes:

• Policy check (X-Shield): verifica as regras configuradas antes de executar. Se uma regra bloquear, levanta OrkaPolicyBlocked
• Execução: sua função original roda normalmente
• Audit log (X-Ledger): resultado, latência e status são registrados com hash SHA-256 encadeado

Funciona com async também

@orka.guard(agent_id="uuid-do-agente", task_type="web_search")
async def buscar(query: str) -> str:
    return await agente.invoke(query)

Fail-safe por design

Se a Orka estiver fora do ar, sua função executa normalmente. O SDK nunca interrompe a produção por falha de conectividade. A única exceção é uma política explicitamente configurada para bloquear — nesse caso, o bloqueio é intencional.

TypeScript / Node.js

import { init, guard } from "orkaia-js";

init({ apiKey: "orka_sua_chave" });

const transferir = guard(
  async (valor: number, destino: string) => api.transferir(valor, destino),
  { agentId: "uuid-do-agente", taskType: "transferencia", risk: "HIGH" }
);

Níveis de risco (EU AI Act)

O campo risk segue a classificação do EU AI Act: UNACCEPTABLE, HIGH, LIMITED, MINIMAL, NONE. Isso alimenta diretamente o relatório de conformidade gerado pelo endpoint GET /compliance/euaiact.

Próximos passos

Nas próximas versões: suporte a LangChain, CrewAI e outros frameworks com wrappers nativos. Por enquanto, qualquer framework funciona — o decorator age na camada de função, não de framework.