qorami

Qorami SDK

为 Qorami 提供的官方客户端、工具架构和 MCP 服务—— 它是 AI Agent 与实际发送邮件之间的控制点。每次发送前， Agent 都会向 Qorami 询问，Qorami 会回复 send、 request_human_confirmation 或 do_not_send。

在控制面板中获取 API 密钥。 完整 API 参考：https://qorami.fr/docs。

路径	内容
js/	零依赖 JavaScript / TypeScript 客户端（fetch，支持 Node 18+ 或浏览器）。
python/	零依赖 Python 客户端（仅使用标准库）+ LangChain、CrewAI、LlamaIndex 和 OpenAI-Agents 工具。
tools/	可直接使用的 OpenAI 函数调用和 Anthropic 工具调用架构，适用于 qorami_check_email。
mcp/	用于 Claude Desktop、Cursor 及任何 MCP 客户端的 Stdio MCP 服务（qorami_health、verify_email、check_action_status）。
n8n-nodes-qorami/	n8n 社区节点（Settings → Community Nodes → n8n-nodes-qorami）——为邮件添加防护，可用作 AI Agent 工具。
n8n/	无代码方案：使用普通 HTTP Request 节点为工作流中的邮件添加防护（无需安装）。
examples/	可运行的 Node 和 Python 快速入门示例。

JavaScript / TypeScript

import { QoramiClient } from './js/qorami.mjs'

const qorami = new QoramiClient({ apiKey: process.env.QORAMI_API_KEY })

await qorami.guard(
  { recipient: '[email protected]', subject: 'Our offer', body, policyProfile: 'sales' },
  {
    send: () => mailer.send(),                            // allowed
    requestHumanConfirmation: (r) => queue(r.action.id), // a human was notified
    doNotSend: (r) => log('blocked', r.decision),        // do not send
  },
)

也可以逐步调用 qorami.verify(...)，审核完成后轮询 qorami.status(actionId)，直到 nextAction.type === 'send'。

Python

from qorami import QoramiClient
qorami = QoramiClient(api_key=os.environ["QORAMI_API_KEY"])

result = qorami.verify(recipient="[email protected]", subject="Our offer",
                       body=email_body, policy_profile="sales")
if result.next_action_type == "send":
    send_email()
elif result.next_action_type == "request_human_confirmation":
    queue_for_review(result.action_id)   # a human was notified by email
# else: do_not_send

Agent 框架工具

pip install qorami[<framework>] 会安装可直接使用的 qorami_check_email 封装—— 每个封装都会返回 ALLOWED / NEEDS HUMAN APPROVAL / BLOCKED，并复用客户端：

框架	安装	导入
LangChain	pip install qorami[langchain]	from qorami_langchain import build_qorami_tool
CrewAI	pip install qorami[crewai]	from qorami_crewai import QoramiEmailGuard
LlamaIndex	pip install qorami[llamaindex]	from qorami_llamaindex import build_qorami_tool
OpenAI Agents SDK	pip install qorami[openai-agents]	from qorami_openai_agents import qorami_check_email

from qorami_langchain import build_qorami_tool
tool = build_qorami_tool()        # reads QORAMI_API_KEY

无代码工作流（n8n）使用普通 HTTP Request 节点——参见 n8n/。

MCP 服务

将 Qorami 注册为 Claude Desktop / Cursor / 任意 MCP 客户端中的原生工具—— 参见 mcp/。它通过 stdio 提供 qorami_health、verify_email 和 check_action_status。

约定

每个客户端都会通过 nextAction.type 返回 Agent 必须遵循的相同决策： send、request_human_confirmation（由人工先行批准——轮询该操作）， 或 do_not_send。参见 https://qorami.fr/docs。

清理后的版本（自动补救）

如果邮件的风险仅来自可通过机械方式移除的内容（泄露的 密钥、可疑链接、IBAN / 卡号 / SSN），验证结果会附带一份清理后、 可发送的副本——发送 remediation.safeBody，而不是直接阻止：

const r = await qorami.verify({ recipient, subject, body, policyProfile: 'general' })
if (r.nextAction.type === 'do_not_send' && r.remediation?.safeToSend) {
  mailer.send({ ...email, body: r.remediation.safeBody })   // safe, redacted copy
}

r = qorami.verify(recipient=..., subject=..., body=email_body)
if r.next_action_type == "do_not_send" and (r.remediation or {}).get("safeToSend"):
    send_email(body=r.remediation["safeBody"])   # safe, redacted copy

remediation.removed 会列出被移除的内容（例如 ["secret", "link"]）。MCP 服务也会提供相同字段。

许可证

MIT——参见 LICENSE。