Algenta MCP Server

定制的 Mojo 内核赋予 Algenta 出色的速度。团队无需编写任何 Mojo 代码——这些构建模块使用 Python 和 TypeScript。在你自己的基础设施上运行，而不是我们的基础设施上。这些 SDK 让 Python 和 TypeScript 能够调用引擎：以类型安全的方式访问受治理的数据查询、蒙特卡洛模拟和推荐；访问决策记忆，其中的执行回执会固定记录每次执行所依据的策略和架构快照；运行包含人工介入审批的 Agent；使用托管连接器；并查看完整的审计记录——所有这些都由引擎强制执行，而非依赖客户端约定。

MCP 服务

MCP 服务（algenta-mcp）——Algenta 官方 MCP 服务位于本仓库的 packages/mcp/（实现位于：packages/mcp/algenta_mcp；默认使用 stdio 传输，可选使用 Streamable HTTP）。使用 pip install algenta-mcp 安装，并通过 algenta-mcp 命令运行；该服务也已列入官方 MCP Registry，名称为 io.github.thyn-ai/algenta。框架集成（LangChain、LlamaIndex、Vercel AI SDK 等）位于配套仓库 thyn-ai/algenta-integrations 中，而非 MCP 服务中。

查看信息（initialize/tools/list）无需凭据。执行工具需要免费的社区账号登录——在 algenta.ai 注册设备（免费）：运行 algenta login，或在 https://app.algenta.ai/dashboard/api-keys 创建密钥，然后设置 ALGENTA_API_KEY。

安装

pip install algenta-sdk       # Python 3.12+
npm install algenta-sdk       # TypeScript / JavaScript, Node.js 18+

快速入门

两个客户端都会从环境中读取 ALGENTA_API_KEY，并默认使用 Algenta 托管的 API：https://api.algenta.ai。

Python — 请注意，导入名称是 decision_engine（参见 旧名称）：

from decision_engine import AlgentaClient

client = AlgentaClient()  # reads ALGENTA_API_KEY; defaults to https://api.algenta.ai

datasets = client.list_datasets(search="orders", compact=True)
summary = client.get_dataset_summary(datasets.datasets[0].dataset_id)
result = client.query_with_metadata(
    {
        "dataset_id": summary.dataset_id,
        "metric": {"hint": "gross_revenue"},
        "aggregation": "sum",
    }
)
print(result.data.result)

TypeScript：

import { AlgentaClient } from "algenta-sdk";

const client = new AlgentaClient(); // reads ALGENTA_API_KEY; defaults to https://api.algenta.ai

const datasets = await client.listDatasets({ search: "orders", compact: true });
const summary = await client.getDatasetSummary(datasets.datasets[0].dataset_id);
const result = await client.queryWithMetadata({
  dataset_id: summary.dataset_id,
  metric: { hint: "gross_revenue" },
  aggregation: "sum",
});
console.log(result.data.result);

使用自托管引擎？ 将客户端指向你自己的部署 — Python 中使用 AlgentaClient(base_url="http://localhost:8000")， TypeScript 中使用 new AlgentaClient({ baseUrl: "http://localhost:8000" }) — 并使用运营方提供的 API 密钥。self_hosted 和 air_gapped 部署配置会在失败时直接报错：绝不会静默回退到 Algenta 的云服务。 thyn-ai/algenta-integrations 中的框架集成有意采用相反的默认策略：优先使用自托管服务，从 ALGENTA_BASE_URL 或显式指定的 base_url 解析端点，并且绝不默认使用或回退到托管 API。

完整的 API 功能 — 受治理的查询、连接器、模拟、作业、 触发器、Agent 运行、决策、代码库智能，以及 TypeScript 本地 Runtime 门面 — 详见 packages/python-sdk/README.md 和 packages/ts-sdk/README.md，可运行的 项目见 examples/。MCP 服务位于此代码库中 （参见上文的 MCP 服务）；框架集成（LangChain、 LlamaIndex、Vercel AI SDK 等）位于配套代码库 thyn-ai/algenta-integrations。

错误、重试和超时

两个 SDK 会抛出相同类别的异常。每个错误都包含 HTTP 状态码、引擎机器可读的 error_code，以及（Python 中的） 引擎分配的 request_id；验证失败还会通过 field_errors（Python）/ fieldErrors（TypeScript）提供逐字段详情。

异常	HTTP 状态码	抛出条件	默认是否重试
AuthenticationError	401	API 密钥缺失或无效	否
NotFoundError	404	资源不存在	否
ValidationError	422	请求未通过架构验证	否
RateLimitError	429	超出配额或速率限制	是 — 遵循引擎的 Retry-After（retry_after / retryAfter，默认 60s）
ServerError	5xx	引擎端故障	是 — 指数退避
DecisionEngineError	任意	以上所有异常的基类	—

临时网络错误会按照与 5xx 响应相同的策略重试。Python SDK 还会对 一个速率限制代码 inline_preview_rate_limited 永不重试。

设置	Python	TypeScript	默认值
请求超时	timeout（秒）	timeout（毫秒）	120
每个请求的重试次数	max_retries	maxRetries	3

旧名称

SDK 在开发过程中曾更名为 Algenta。为保持向后兼容，以下旧名称仍然有效 — 现有代码和部署配置无需更改：

• Python 导入名称 — PyPI 包名为 algenta-sdk，但 可导入模块仍为 decision_engine： from decision_engine import AlgentaClient。
• 客户端别名 — 在两个 SDK 中，CodnaClient（以及 Python 中的 AsyncCodnaClient）仍导出为 AlgentaClient 的别名。
• 环境变量 — 除了标准的 ALGENTA_API_KEY 和 ALGENTA_BASE_URL，仍接受 DE_API_KEY、DE_BASE_URL 和 ALGENTA_API_URL。

已发布的 API 合约保证，在移除任何旧名称前提供 90 天的弃用窗口 （DEPRECATION_WINDOW_DAYS）。

由 Mojo 提供支持

引擎的计算内核——包括模拟、评分和本地查询执行——使用 Mojo 编写，且为专有内容。它们以签名的 algenta-runtime-native wheels 形式分发，不属于此仓库。

此处以及 Apache-2.0 许可下开放的内容包括：两个 SDK、据此生成的已发布 API 契约、它们使用的客户端／运行时线路协议，以及可运行示例——包括 examples/mojo-quickstart/，这是一个通过 SDK 调用本机运行时的端到端精简演示。

哪些内容是开源的？

此仓库包含 Algenta 的 Python 和 TypeScript 客户端 SDK，以及官方 MCP 服务（packages/mcp/），采用 Apache-2.0 许可（详见 LICENSE 和 NOTICE）。

Algenta 引擎本身为闭源，且不包含在此仓库中。 引擎许可证、设备授权、工作器限制、并发限制和 Server Compute Units 均由引擎独立执行，并受单独的 Algenta Engine 许可证约束。

SDK 是一个纯 HTTP 客户端。它不持有用于签署许可证的密钥，不包含授权执行逻辑，也不与引擎共享任何机密——每项授权声明都由闭源引擎独立验证并执行，而绝非由此 SDK 执行。你可以派生此项目、删除其中的所有检查，或者完全换成自己的 HTTP 客户端——修改或替换此 SDK 不会改变 Algenta 引擎获得许可的执行能力。 有关漏洞报告的含义，请参阅 SECURITY.md。

Algenta 不要求执行时使用托管推理或遥测。付费许可证扩展的是本地执行和治理能力，而不是按 SDK 调用次数收费。

验证发行版本

release.yml 构建的每个发行版本都与以下内容绑定：

• 此仓库中受保护的 sdk-vX.Y.Z 源代码标签；
• 该标签指向的确切提交；
• 一份发行授权记录，该记录由内部发行流水线在引擎的测试套件验证该提交后签署，并将该提交及契约文件摘要与待发布版本绑定（详见 releases/）。

除非以上所有内容均独立匹配，否则 release.yml 不会构建或发布任何内容——详见 scripts/verify_release_authorization.py。

自添加签名以来（2026 年 9 月），每个发布的 GitHub Release 都会在 wheel 旁附带 sdist 和 release-manifest.json：

• 每项资产对应一个无密钥的 Sigstore 签名包（<asset>.sigstore.json），由 release.yml 运行本身签署；
• 涵盖全部三项资产的 SLSA 构建来源证明（multiple.intoto.jsonl），由 SLSA 通用生成器提供。

若要同时依据两者检查资产，请将 VERSION 设为发行版本号（标签 sdk-v1.0.15 对应 VERSION=1.0.15）：

pipx run sigstore verify identity "algenta_sdk-${VERSION}-py3-none-any.whl" \
  --bundle "algenta_sdk-${VERSION}-py3-none-any.whl.sigstore.json" \
  --cert-oidc-issuer https://token.actions.githubusercontent.com \
  --cert-identity "https://github.com/thyn-ai/algenta-sdk/.github/workflows/release.yml@refs/tags/sdk-v${VERSION}"

slsa-verifier verify-artifact "algenta_sdk-${VERSION}-py3-none-any.whl" \
  --provenance-path multiple.intoto.jsonl \
  --source-uri github.com/thyn-ai/algenta-sdk \
  --source-tag "sdk-v${VERSION}"

通过 release.yml 的 workflow_dispatch 路径发布的发行版本，是从手动触发的分支签署的，因此其证书身份以 @refs/heads/main 结尾，而不是标签；签名包会记录具体情况。

版本控制

两个软件包共用一个版本号，因为它们封装的是同一个 API 契约，并遵循 语义化版本：

• 补丁版本——错误修复和文档更新；不更改 API 表面。
• 次要版本——向后兼容的新增内容（新方法、新可选字段）。
• 主要版本——导出符号、必需字段或行为发生不兼容更改；会通过上述弃用期提前公告。

发行历史记录在 CHANGELOG.md 中。

贡献

欢迎提交错误修复、框架集成、文档和测试，详见 CONTRIBUTING.md。无需签署 CLA：根据 GitHub 的服务条款，贡献内容遵循「授权进来、授权出去」原则，采用 Apache-2.0 许可。 新 API 功能通常需要先修改 Algenta 的私有 API；请提交 issue 描述所需功能，而不是针对生成的契约文件提交 PR（CONTRIBUTING.md 中也有说明）。

另请阅读 CODE_OF_CONDUCT.md。

• 安全问题报告 → SECURITY.md（切勿提交公开 issue）
• 项目方向与维护工作 → GOVERNANCE.md
• 获取帮助 → SUPPORT.md

贡献者

感谢所有为本项目作出贡献的人——我们遵循 all-contributors 规范，并认可 各种形式的贡献， 而不仅仅是代码贡献。

社区

• Discord
• 文档
• [email protected]

相关仓库

Algenta 团队围绕 Algenta 构建的开源工具。Algenta 引擎本身是专有软件；以下列出的所有内容均采用 Apache-2.0 许可。欢迎在拥有相关代码的仓库中提交 issue 和参与讨论。

• thyn-ai/algenta-sdk（本仓库）— Algenta 的 Python 和 TypeScript SDK，以及官方 MCP 服务 (packages/mcp/)：受治理的数据查询、模拟、带执行回执的决策记忆，以及带审批的 Agent 运行。
• thyn-ai/algenta-integrations — Algenta 的框架集成：LangChain、LlamaIndex、pydantic-ai、MAF、Haystack、LiteLLM、Ray Serve、vLLM、Vercel AI SDK 和 n8n。
• thyn-ai/mojo-kernels — 清洁室实现的 Mojo 内核，可作为热门 Python/TypeScript 库的即插即用加速器，提供位级精确的兼容性和纯语言回退方案。
• thyn-ai/security-toolchain — 固定版本且经过校验和验证的安全工具链（Gitleaks、Opengrep、OSV-Scanner、Trivy config、actionlint），每个 thyn-ai 仓库都会在本地和 CI 中运行它。
• thyn-ai/feedback — 用于提交与 Algenta 相关的开源工具和 Codna GitHub App 问题的公开入口。
• thyn-ai/codna-action — Codna 的 GitHub Action：通过与 CLI 使用的同一打包本地运行时，在 CI 中修复、审查或保护仓库。