Immiscible（AI Agent 治理与签名收据 SDK） Skill 技能

技能简介

Immiscible 是面向 AI Agent 的治理 SDK（Python 3.9+），用一行 with run.guard(...) 在工具调用前自动询问授权、按需叫人审批、执行后留下 Ed25519 签名收据，覆盖 OpenAI Agents SDK、LangChain、LangGraph 与 MCP 客户端。整套实现仅依赖 Python 标准库（urllib、json、hashlib + 纯 Python Ed25519 验证器），体积小、可审计、易嵌入；为 AI Agent 加上"花费上限、审批闸门、不可抵赖收据"三件套，让 Agent 在企业级合规场景里真正可被信任。

核心能力

1. Guard 上下文/装饰器：with run.guard(tool_action(...)): 在工具调用前向 Immiscible 询问授权，授权失败抛 ImmiscibleDeniedError 且用户代码不会被执行；支持 async 函数装饰器用法。
2. 人工审批流转：当需要人工决策时，wait_for_decision() 以指数退避 + 抖动策略轮询决策状态，可随时通过 threading.Event 取消。
3. 签名收据：每次允许/拒绝/结算动作都返回 Ed25519 签名 receipt，包含 trace、session、action、idempotency_key 等字段，便于审计与不可抵赖。
4. TokenOps：调用 outcome(task_id, status) 汇总任务级 token 消耗与结果状态，便于按 trace 维度做成本与 SLA 分析。
5. MCP 代理：mcp_proxy(upstream_id) 提供 list_tools、call、call_with_approval、retry_after_approval，把 MCP 工具包纳入统一治理。
6. 多模型网关：内置 gateway.openai() / gateway.anthropic() / gateway.openai_client() / gateway.anthropic_client() / gateway.env()，在 run 上下文内把模型调用也纳入治理与收据。
7. 支付与数据动作：pay(...) / request_data(...) 与 Immiscible.payment_action(...) / Immiscible.data_action(...) 帮助构造与发送结构化 action。

安装配置

1. 安装：pip install immiscible，无需额外系统依赖。
2. 凭据准备：在 Immiscible 控制台创建 Agent Key，设置 IMMISCIBLE_AGENT_KEY 环境变量（旧名 ASSAY_AGENT_KEY 仍兼容）；可选设置 IMMISCIBLE_URL 指向私有部署，默认连 https://immiscible.fly.dev。
3. 上下文与 traceparent：Immiscible(api_key, base_url, timeout=30, max_retries=2, session_id=..., traceparent=...) 可显式覆盖默认值，便于与现有 OpenTelemetry trace 关联。
4. 装饰器映射：装饰器形式 guard(action_mapper) 把函数返回值映射成 action，sync 与 async 均支持。
5. 失败安全：缺凭据时 Immiscible 默认 "fails closed"——任何不可达的授权请求都会拒绝执行，不放过任何未授权动作。

使用步骤

1. 创建 Immiscible 客户端：immiscible = Immiscible()，自动读取 IMMISCIBLE_AGENT_KEY 与 IMMISCIBLE_URL。
2. 创建一次运行：run = immiscible.run()，得到一条 trace 与一个 session。
3. 在工具调用前包裹 guard：with run.guard(tool_action("deploy", {"service": "api"}, domain="mycompany.com")): deploy()。
4. 如需人工审批：decision = immiscible.decide(action)，返回 allowed 为 True 继续、为 False 抛 ImmiscibleDeniedError。
5. 执行后调用 settle(id, status="completed") 记录结果，server 端生成 Ed256 签名 receipt。
6. 如需 TokenOps 汇总：immiscible.outcome(task_id, "completed")，把消耗与状态写入 trace。
7. 对 MCP 工具：proxy = immiscible.mcp_proxy("my-mcp")，再 proxy.call_with_approval(tool, args)。

适用场景

• 企业级 Agent 部署：所有工具调用强制经 Immiscible 授权并留下签名收据，方便审计与合规。
• 金融与医疗 Agent：涉及转账、写入 EMR 等敏感动作时强制走人工审批闸门。
• 多 Agent 协作场景：每个 Agent 分配独立 session_id，按 trace 维度追踪成本与责任归属。
• 跨平台工具治理：同时使用 OpenAI Agents、LangChain、LangGraph 与 MCP，统一接入 Immiscible。
• 学术与评测：研究者把 Agent 行为接入 Immiscible，自动生成可重复的治理 trace 数据集。

适用人群

• 在企业内引入 AI Agent 的架构师与平台工程师。
• 需要满足 SOC2/ISO 27001/HIPAA 等合规要求的 AI 产品负责人。
• 担忧 Agent 误操作风险的金融、医疗、法律 SaaS 厂商。
• 研究 Agent 治理、TokenOps、Agent 经济学的学者与工程师。

工作原理

Immiscible 在客户端与 Immiscible Server 之间走 HTTPS：客户端把每次工具调用抽象成带 idempotency_key、traceparent、session_id 的 action 请求，Server 端对照预先注册的 mandate 决策；如需人工审批则返回 approval_url，客户端用 wait_for_decision 轮询；任何结果（allow / deny / settled）都附带 Ed25519 签名 receipt（基于纯 Python 实现，零第三方依赖）。整套 SDK 仅使用 Python 标准库（urllib + json + hashlib + Ed25519 verifier），保证可审计与可嵌入；OpenAI Agents、LangChain、LangGraph 与 MCP 都能通过 gateway / proxy 接入统一治理。

官方链接

• PyPI：https://pypi.org/project/immiscible/
• 官网：https://immiscible.fly.dev
• 快速上手：https://immiscible.fly.dev/docs/quickstart
• API：https://immiscible.fly.dev/docs/api
• SDK 文档：https://immiscible.fly.dev/docs/sdks
• 源码：https://github.com/efr7-7/immiscible-sdks/tree/main/packages/immiscible-py
• Issues：https://github.com/efr7-7/immiscible-sdks/issues