Metadata-Version: 2.4
Name: licos-agent-runtime
Version: 0.2.36
Summary: LICOS Python agent runtime for LangGraph/LangChain projects
Requires-Python: >=3.10
Requires-Dist: fastapi<1,>=0.121
Requires-Dist: filelock<4,>=3.16
Requires-Dist: httpx<1,>=0.27
Requires-Dist: langchain-openai<2,>=1.2
Requires-Dist: langchain<2,>=1.2
Requires-Dist: langgraph-checkpoint-postgres<4,>=3.0
Requires-Dist: langgraph-checkpoint<5,>=4
Requires-Dist: langgraph-prebuilt<2,>=1.0
Requires-Dist: langgraph-sdk<1,>=0.3
Requires-Dist: langgraph<2,>=1.1
Requires-Dist: langsmith<1,>=0.4
Requires-Dist: licos-platform-sdk>=0.5.6
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: uvicorn<1,>=0.38
Description-Content-Type: text/markdown

# LICOS Agent Runtime

`build_agent_graph(model, tools, system_prompt=...)` 提供统一的输入 → 模型 → 工具循环，模型与工具由项目注册。`input`、`messages`、`event` 可以组合使用；模型调用保留完整工具消息对，多模态输入保持原始内容。

```bash
python -m licos_agent_runtime -m verify --cases tests/agent_cases.json --base-url http://127.0.0.1:5000 --report .tmp/agent-verification.json
```

验收连接已有预览，核对 HTTP、SSE、模型/业务工具调用与运行记录。业务场景在用例中指定 `required_tools` 和 `model_contains`；报告引用实际 run_id，错误导致非零退出码。

## 本体事件执行

业务项目运行时可通过 `config/event_subscriptions.json` 管理后台订阅。默认空数组，不建立订阅。浏览器断开不影响已启动的服务；预览进程或项目实例休眠后订阅会停止，持续监听需要部署为常驻业务服务。该功能不保证唤醒已休眠的开发实例。

先对项目运行 `python -m licos_agent_runtime -m fingerprint` 取得当前源码版本，再配置绑定：

```json
[
  {
    "id": "process-observation",
    "workspace_id": "当前工作空间 ID",
    "project_id": "当前业务 AGENT 项目 ID",
    "project_version": "fingerprint 命令返回的 SHA256",
    "element_ids": ["已从本体目录解析的元素 ID"],
    "attribute_ids": ["已授权的属性 ID"],
    "enabled": true,
    "max_pending": 100
  }
]
```

`max_pending` 由业务配置，没有写死容量。每个绑定按接收顺序串行执行，绑定之间可并行。源码版本与运行时热更新使用同一份源文件集合；绑定配置本身不参与指纹，避免自引用。源码或模型配置变化后需要重新验收、更新版本绑定并重启服务。身份与当前项目不匹配、版本不匹配、参数或权限错误都会明确失败。

- `GET /agent/subscriptions` 查看绑定、连接状态、最近执行及错误。
- `POST /agent/subscriptions/{id}/stop` 停止当前订阅和执行。
- `POST /agent/subscriptions/{id}/start` 启动已加载的绑定。配置文件新增或修改绑定后重启服务使其加载。

事件通过 SDK 接收后写入 `/workspace/.licos/event-subscriptions/deliveries.sqlite3`，直接调用本项目的业务图，不调用编程助手 `/messages`。已有日程任务针对会话，因此这里持久化业务运行时自己的投递队列，并复用工作区持久卷和运行记录。文件锁阻止共享同一工作区的多个运行时重复监听。实际执行前经过与 `/run` 相同的余额检查。

每次投递保留原始事件、绑定、源码/运行时版本以及 run_id，模型和工具证据可在 `/run_records/{run_id}` 查阅。待执行事件随服务重启恢复；运行中断标记为 `interrupted`，失败标记为 `failed`，均不自动重放。积压达到配置上限时记录该事件失败并停止订阅，错误可查询。

当前上游协议未承诺稳定事件身份或断线回放：相同时间和值的事件全部保留，运行时生成的投递 ID 仅用于本地追踪，不代表上游事件 ID。已接收且落盘的待执行事件可恢复，连接中断期间的上游事件无法保证补齐。人工/历史回放使用普通事件输入并保留真实来源，不能当作 WS 新事件验收。

## 用量

SSE 完成事件和运行记录共用模型用量汇总；`token_usage.complete=false` 表示至少一次模型调用没有用量记录。已统计数值仅是已知部分，不能把未上报当成零消耗。
