Metadata-Version: 2.4
Name: licos-agent-runtime
Version: 0.2.37
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，错误导致非零退出码。

运行执行超时与验收 HTTP 等待时间统一读取 `LICOS_AGENT_RUN_TIMEOUT_SECONDS`，未设置时默认 900 秒。验收可以用 `--request-timeout` 显式覆盖 HTTP 等待时间，并在报告中记录实际值；该参数不修改服务端执行预算。HTTP 等待时间是请求各网络阶段的等待限制，服务端预算是一次图执行的总时限。空值、非数字、非有限数及非正数会明确失败；服务端在创建任务前校验配置。工具自身的 `TimeoutError` 保留原错误，不当作运行时预算耗尽。

项目导出的图在加载时校验 `ainvoke`、`stream`、`astream`、`astream_events` 接口及调用参数。统一传递 `config/context`；异步流还支持 `stream_mode`，调试事件使用 `version="v2"`。可以直接导出编译后的 LangGraph 图。接口不匹配、无法检查工厂签名或缺失流式方法会失败；执行异常不会触发换参数重试或切换执行方式。

## 本体事件执行

业务项目运行时可通过 `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` 查看绑定、连接状态及订阅错误。
- `GET /agent/subscriptions/{id}/deliveries?limit=...&offset=...` 分页查询投递记录及执行错误，返回 `records/total/limit/offset`。`limit` 必须显式传入正整数，`offset` 默认 0 且必须非负；不会固定截为 50 条或静默修改分页参数。未知绑定返回 404，非法参数返回 422。
- `POST /agent/subscriptions/{id}/stop` 停止当前订阅和执行。
- `POST /agent/subscriptions/{id}/start` 启动已加载的绑定。配置文件新增或修改绑定后重启服务使其加载。

0.2.37 起，订阅状态响应不再内嵌 `deliveries`，调用方通过分页接口读取投递记录。

事件通过 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` 表示至少一次模型调用没有用量记录。已统计数值仅是已知部分，不能把未上报当成零消耗。
