Ordin Agent Runtime

Ordin 是一个模型中立、平台无关的 Python Agent Runtime。宿主平台提供已认证身份、持久化的用户消息、 Conversation 引用、不可变资源快照和运行时 Ports；Ordin 执行完整 Agent 链路：意图识别、 direct/clarify/Mission 路由、Task DAG、动态 sub-Agent、Context/LLM/Tool 循环、结果验收与最终聚合。

Ordin Core 不实现消息队列、Worker host、PostgreSQL 或具体对象存储。它定义领域模型、窄 Port、 CAS/原子提交/fencing/effect-ledger 合同，并在 ordin.testing 提供可执行的内存参考 Adapter。

PyPI distribution 和 Python 导入命名空间统一为 ordin。

安装与校验

从 PyPI 安装：

pip install ordin

源码开发与完整校验：

uv sync
uv run python scripts/docs.py --check
uv run pytest tests/test_docs.py
uv run ruff format .
uv run ruff check .
uv run ty check
uv run pytest

最小示例

下面用内存 Adapter 模拟平台先持久化 UserMessage、再提交 ExecutionRequest。生产平台应以自己的 事务存储和对象存储实现相同 Ports。

from ordin.agent import Agent
from ordin.common import Identity
from ordin.llm import LLMCallPipeline, LLMProfile
from ordin.mission import ConcatAggregator, SingleTaskPlanner
from ordin.observability import EventBroker
from ordin.runtime import Runtime
from ordin.testing import InMemoryObjectStore, InMemoryRuntimeBackend

backend = InMemoryRuntimeBackend()
events = EventBroker(backend)
llm_calls = LLMCallPipeline(
    provider=my_llm_provider,
    recorder=backend,
    event_sink=events,
)
runtime = Runtime(
    llm_calls=llm_calls,
    events=events,
    llm_profile=LLMProfile(id="private-model"),
    backend=backend,
    object_store=InMemoryObjectStore(),
    direct_agent=Agent[None](name="direct", instructions="Answer the request."),
    planner=SingleTaskPlanner(),
    aggregator=ConcatAggregator(),
    enable_memory_tools=False,
)

identity = Identity(user_id="u-1")
request = await backend.prepare_execution(
    "实现一个可测试的分析流程",
    identity=identity,
)
result = await runtime.execute(request, context=None)

Runtime.start() 返回 direct/clarify 结果或 MissionHandle；Runtime.execute() 等待完整执行完成。 两者都只接受平台已经装配好的 ExecutionRequest，不会接收并持久化原始用户消息。

当同一 Branch 已有活跃 Execution 时，平台不应再创建并发 Execution，而应在同一事务追加 Conversation UserMessage 和 SupervisorMessage。Supervisor 会把消息分类为指导、目标修订、状态 查询、取消、暂停、恢复或后继目标。内存参考 Adapter 的 append_supervisor_text() 展示了该原子入口。

生产组合

推荐使用 PostgreSQL 保存 Conversation、Execution/Mission、Plan/Task、command cursor、LLM call、 effect ledger 和 Artifact metadata，使用 S3/MinIO 等对象存储保存大字节。队列、lease、Worker 部署、 认证、租户、配额和资源授权都由宿主平台负责。平台的 execution authority 必须在每次关键提交前 检查所有权；外部 Tool 副作用仍需幂等键、对账和 needs_attention，不能宣称 exactly-once。

文档

• 文档入口
• 架构总览
• Runtime 与 Supervisor
• Ports 与生产 Adapter
• 快速开始
• 平台 Adapter 指南
• 代码树 与 公开 API
• ADR-0007：平台无关 Runtime
• ADR-0008：Supervisor Inbox

可运行示例位于 examples/；其中 examples/csv_subagent.py 展示平台冻结资源快照并构造 ExecutionScope 的完整离线路径。