# agent-platform

基于 Python 的多服务智能体开发平台脚手架。

当前仓库已经初始化为 Monorepo，包含：

- `services/`：核心微服务
- `libs/`：共享领域模型、DSL、事件、数据库和公共组件
- `deployments/`：本地和集群部署占位
- `docs/`：规划和数据库设计文档

## 当前已创建的服务

- `api-gateway`
- `session-service`
- `workflow-service`
- `runtime-service`
- `tool-service`

每个服务都提供了最小 `FastAPI` 启动入口和健康检查接口，数据库相关服务也已经带上了 `SQLAlchemy` 模型骨架与 Alembic 目录。

## 当前已创建的共享库

- `core-domain`
- `core-dsl`
- `core-events`
- `core-shared`
- `core-db`

## 推荐本地开发方式

建议使用 `uv` 或 `pip` 创建虚拟环境后安装各服务依赖。

```powershell
cd D:\workspace\auto-platform
python -m venv .venv
.venv\Scripts\activate
pip install -e .\libs\core-shared
pip install -e .\libs\core-domain
pip install -e .\libs\core-dsl
pip install -e .\libs\core-events
pip install -e .\libs\core-db
pip install -e .\services\api-gateway
pip install -e .\services\session-service
pip install -e .\services\workflow-service
pip install -e .\services\runtime-service
pip install -e .\services\tool-service
```

运行示例：

```powershell
cd D:\workspace\auto-platform\services\api-gateway
uvicorn app.main:app --reload --port 8000
```

数据库连接默认使用各服务目录下的 SQLite 文件，也可以通过环境变量覆盖：

```powershell
$env:AGENT_PLATFORM_DATABASE_URL="postgresql+psycopg://user:password@localhost:5432/workflow_db"
```

## 数据层脚手架

本轮已经加入：

- `libs/core-db`：统一 `SQLAlchemy` Base、通用 mixin、命名约定
- `workflow-service`：应用与流程定义模型
- `session-service`：会话与消息模型
- `runtime-service`：运行与节点执行模型
- `tool-service`：工具定义与绑定模型
- 每个服务独立的 `alembic.ini`、`env.py`、`versions/`
- `workflow-service`：已接入 repository / application service / CRUD API
- `session-service`：已接入 repository / application service / CRUD API

迁移执行示例：

```powershell
cd D:\workspace\auto-platform\services\workflow-service
alembic upgrade head
```

其他服务同理：

- `services/session-service`
- `services/runtime-service`
- `services/tool-service`

接口示例：

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8002/workflows/apps `
  -ContentType "application/json" `
  -Body '{"tenant_id":"t1","code":"sales_assistant","name":"Sales Assistant"}'
```

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8001/sessions `
  -ContentType "application/json" `
  -Body '{"tenant_id":"t1","app_id":"app-1","user_id":"user-1","channel_type":"web"}'
```

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8002/workflows/versions `
  -ContentType "application/json" `
  -Body '{"tenant_id":"t1","workflow_id":"wf-1","dsl_json":{"nodes":[],"edges":[]}}'
```

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8001/sessions/run-requests `
  -ContentType "application/json" `
  -Body '{"tenant_id":"t1","session_id":"sess-1","app_version_id":"appv-1","workflow_version_id":"wfv-1"}'
```

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8003/runtime/runs `
  -ContentType "application/json" `
  -Body '{"tenant_id":"t1","app_id":"app-1","app_version_id":"appv-1","workflow_id":"wf-1","workflow_version_id":"wfv-1","session_id":"sess-1","initial_node":{"node_id":"start","node_type":"llm"}}'
```

如果不传 `initial_node`，`runtime-service` 会调用 `workflow-service` 读取对应的 `workflow version`，并从 DSL 中自动推导首节点：

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8003/runtime/runs `
  -ContentType "application/json" `
  -Body '{"tenant_id":"t1","app_id":"app-1","app_version_id":"appv-1","workflow_id":"wf-1","workflow_version_id":"wfv-1","session_id":"sess-1"}'
```

一条链直接派发到 runtime：

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8001/sessions/run-requests/dispatch `
  -ContentType "application/json" `
  -Body '{"tenant_id":"t1","session_id":"sess-1","app_id":"app-1","app_version_id":"appv-1","workflow_id":"wf-1","workflow_version_id":"wfv-1","initial_node":{"node_id":"start","node_type":"llm"}}'
```

工具定义示例：

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8004/tools `
  -ContentType "application/json" `
  -Body '{"tenant_id":"t1","code":"search_products","name":"Search Products","tool_type":"http"}'
```

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8004/tools/versions `
  -ContentType "application/json" `
  -Body '{"tenant_id":"t1","tool_id":"tool-1","input_schema_json":{"query":{"type":"string"}},"invoke_config_json":{"method":"GET","path":"/products/search"}}'
```

运行状态推进示例：

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8003/runtime/node-runs/node-run-id/status `
  -ContentType "application/json" `
  -Body '{"status":"running","worker_key":"runtime-worker-1"}'
```

```powershell
Invoke-RestMethod -Method Post `
  -Uri http://127.0.0.1:8003/runtime/runs/run-id/status `
  -ContentType "application/json" `
  -Body '{"status":"completed"}'
```

说明：

- 当你调用 `node-runs/{node_run_id}/status` 更新节点状态时，`runtime-service` 会自动聚合当前运行下所有 `node_run` 的状态，并同步刷新 `workflow_run.status`
- 当前规则是：任一节点 `failed` 则运行 `failed`；有节点 `running` 则运行 `running`；全部节点都为 `completed/skipped` 则运行 `completed`
- 当某个 `node_run` 被更新为 `completed` 时，`runtime-service` 还会基于 `workflow version` 的 DSL 自动查找后继节点，并创建新的 `queued` 状态 `node_run`

## 目录结构

```text
services/
  api-gateway/
  session-service/
  workflow-service/
  runtime-service/
  tool-service/
libs/
  core-domain/
  core-dsl/
  core-events/
  core-shared/
  core-db/
deployments/
  docker/
  k8s/
docs/
tests/
```

## 下一步建议

1. 补齐 `V0.1` 的 repository / service 层
2. 写第一版 Alembic 初始迁移
3. 接入 PostgreSQL / Redis
4. 增加 Docker Compose
5. 开始实现应用、流程、运行三条主链路