268 lines
8.3 KiB
Python
268 lines
8.3 KiB
Python
# ============================================================
|
||
# Pi Agent 外向接入 API（moduleId: gateway-agent-api, 可重生 ✅）
|
||
# 方向 A · P1：/api/agent/* 薄适配层。
|
||
# - 目录派生自 tool_runtime 只读白名单 + harness _POWER_MAP P0；
|
||
# - invoke 只直通目录内意图；P1/P2 返回 CONFIRM_REQUIRED，P3 返回 POWER_DENIED；
|
||
# - 所有业务委托 run_tool_async / handle_intent，绝不复制或旁路写路径。
|
||
# ============================================================
|
||
from __future__ import annotations
|
||
|
||
import logging
|
||
import uuid
|
||
from typing import Any
|
||
|
||
from fastapi import APIRouter
|
||
from fastapi.responses import JSONResponse
|
||
from pydantic import BaseModel, ConfigDict, Field
|
||
|
||
from server.contracts import INTERFACE_VERSION
|
||
|
||
logger = logging.getLogger(__name__)
|
||
router = APIRouter(prefix="/api/agent", tags=["pi-agent"])
|
||
|
||
|
||
# P1 agent catalog is an explicit allowlist, not an automatic projection of P0
|
||
# intents: tool_runtime/readonly naming has historically mixed in handlers that
|
||
# write the world, knowledge base, or report files (data.analyze/folder.analyze/
|
||
# report.generate). Keeping the list explicit means a future P0 registration
|
||
# does not silently become reachable by an external read-only agent token.
|
||
_AGENT_CATALOG_INTENTS = frozenset(
|
||
{
|
||
"help",
|
||
"guidance.next",
|
||
"master.query",
|
||
"plan.buckets",
|
||
"plan.rccp",
|
||
"plan.feasibility",
|
||
"plan.inventory",
|
||
"plan.leveling",
|
||
"plan.supply",
|
||
"plan.trace",
|
||
"knowledge.query",
|
||
"scenario.compare",
|
||
"order.pool",
|
||
"conflict.list",
|
||
"flex.capacity",
|
||
"flex.compare",
|
||
"flex.simulate_due",
|
||
"skill.list",
|
||
"query.kpi",
|
||
}
|
||
)
|
||
|
||
|
||
class AgentInvokeRequest(BaseModel):
|
||
"""Pi Agent 只读意图调用请求（模块级模型，防止 OpenAPI 前向引用失败）。"""
|
||
|
||
model_config = ConfigDict(extra="forbid")
|
||
|
||
intent: str = Field(min_length=1, max_length=128)
|
||
params: dict[str, Any] = Field(default_factory=dict)
|
||
requestId: str | None = Field(default=None, max_length=128)
|
||
sessionId: str | None = Field(default=None, max_length=128)
|
||
|
||
|
||
def _parameter_schema() -> dict[str, Any]:
|
||
"""保守意图参数槽：不臆造各意图业务字段，未知键由服务端登记语义处置。"""
|
||
return {
|
||
"type": "object",
|
||
"title": "意图参数",
|
||
"description": "参数透传槽位；多数只读查询可传空对象。服务端对未登记/越权行为 fail closed。",
|
||
"properties": {},
|
||
"additionalProperties": True,
|
||
}
|
||
|
||
|
||
def _catalog_items() -> list[dict[str, Any]]:
|
||
from server.agent_core import harness
|
||
|
||
entries: list[dict[str, Any]] = []
|
||
for name in sorted(_AGENT_CATALOG_INTENTS):
|
||
power = harness.power_of(name)
|
||
entries.append(
|
||
{
|
||
"name": name,
|
||
"power": power,
|
||
"description": harness._POLICY_DESC.get(
|
||
name, "Pi Agent 只读 APS 查询/分析意图"
|
||
),
|
||
"readOnly": True,
|
||
"parameters": _parameter_schema(),
|
||
}
|
||
)
|
||
return entries
|
||
|
||
|
||
def _catalog_map() -> dict[str, dict[str, Any]]:
|
||
return {item["name"]: item for item in _catalog_items()}
|
||
|
||
|
||
def _not_found(message: str) -> JSONResponse:
|
||
return JSONResponse(
|
||
status_code=404,
|
||
content={
|
||
"ok": False,
|
||
"error": {"code": "INTENT_NOT_FOUND", "message": message},
|
||
},
|
||
)
|
||
|
||
|
||
def _deny(
|
||
store: Any,
|
||
*,
|
||
intent: str,
|
||
power: str,
|
||
actor: str,
|
||
code: str,
|
||
message: str,
|
||
request_id: str,
|
||
status_code: int,
|
||
) -> JSONResponse:
|
||
try:
|
||
from server.agent_core.audit import write_audit
|
||
|
||
write_audit(
|
||
store.data,
|
||
store.next_id,
|
||
actor=actor,
|
||
category="AGENT",
|
||
action="agent.invoke.denied",
|
||
target={"type": "INTENT", "id": intent},
|
||
power=power,
|
||
rationale={
|
||
"reason": code,
|
||
"requestId": request_id,
|
||
"source": "pi-agent-gateway",
|
||
},
|
||
result="DENIED",
|
||
)
|
||
store.save()
|
||
except Exception:
|
||
logger.warning("agent invoke denied audit failed for %s", intent, exc_info=True)
|
||
return JSONResponse(
|
||
status_code=status_code,
|
||
content={"ok": False, "error": {"code": code, "message": message}},
|
||
)
|
||
|
||
|
||
@router.get("/intents", response_model=None)
|
||
def list_intents() -> dict[str, Any]:
|
||
"""返回当前只读目录，供 Pi 动态生成工具清单。"""
|
||
return {
|
||
"ok": True,
|
||
"scope": ["read"],
|
||
"intents": _catalog_items(),
|
||
"interfaceVersion": INTERFACE_VERSION,
|
||
}
|
||
|
||
|
||
@router.get("/intents/{name}", response_model=None)
|
||
def get_intent(name: str) -> dict[str, Any] | JSONResponse:
|
||
"""返回单个意图的参数目录项。"""
|
||
key = str(name or "").strip()
|
||
item = _catalog_map().get(key)
|
||
if item is None:
|
||
return _not_found(f"意图「{key}」不在只读目录")
|
||
return item
|
||
|
||
|
||
@router.post("/invoke", response_model=None)
|
||
async def invoke(req: AgentInvokeRequest) -> dict[str, Any] | JSONResponse:
|
||
"""执行目录内只读意图，业务委托统一工具运行时。"""
|
||
from server.agent_core import harness
|
||
from server.agent_core.tool_runtime import is_registered, run_tool_async
|
||
from server.auth.context import get_identity
|
||
from server.contracts import IntentResult
|
||
from server.state.store import get_store
|
||
|
||
identity = get_identity(required=True)
|
||
actor = (
|
||
f"pi-agent:{identity.username}"
|
||
if identity.auth_kind == "agent"
|
||
else identity.username
|
||
)
|
||
request_id = (req.requestId or "").strip() or uuid.uuid4().hex
|
||
name = (req.intent or "").strip()
|
||
store = get_store()
|
||
|
||
if not is_registered(name):
|
||
return _deny(
|
||
store,
|
||
intent=name,
|
||
power=harness.power_of(name),
|
||
actor=actor,
|
||
code="INTENT_NOT_REGISTERED",
|
||
message=f"意图「{name}」未登记，拒绝执行",
|
||
request_id=request_id,
|
||
status_code=404,
|
||
)
|
||
|
||
power = harness.power_of(name)
|
||
if name not in _catalog_map():
|
||
if power == "P3":
|
||
return _deny(
|
||
store,
|
||
intent=name,
|
||
power=power,
|
||
actor=actor,
|
||
code="POWER_DENIED",
|
||
message="该意图属于 P3 外部副作用，Pi Agent 只读接入无权执行",
|
||
request_id=request_id,
|
||
status_code=403,
|
||
)
|
||
return _deny(
|
||
store,
|
||
intent=name,
|
||
power=power,
|
||
actor=actor,
|
||
code="CONFIRM_REQUIRED",
|
||
message="该意图尚未开放给 Pi Agent 直通，需人工确认后才能执行",
|
||
request_id=request_id,
|
||
status_code=409,
|
||
)
|
||
|
||
session_id = (req.sessionId or "").strip() or f"agent:{actor}"
|
||
intent = IntentResult.model_construct(
|
||
intent=name,
|
||
params=dict(req.params or {}),
|
||
confidence=1.0,
|
||
source="RULE_FAST",
|
||
)
|
||
try:
|
||
reply = await run_tool_async(store, session_id, intent, actor=actor)
|
||
except Exception as exc:
|
||
logger.exception("agent invoke upstream failed for %s", name, exc_info=exc)
|
||
return JSONResponse(
|
||
status_code=502,
|
||
content={
|
||
"ok": False,
|
||
"error": {
|
||
"code": "UPSTREAM_FAILED",
|
||
"message": "上游业务处理失败，本次调用未完成",
|
||
"requestId": request_id,
|
||
},
|
||
},
|
||
)
|
||
|
||
dumped = reply.model_dump()
|
||
blocks = list(dumped.get("blocks") or [])
|
||
evidence_refs: list[str] = []
|
||
for block in blocks:
|
||
for ref in block.get("evidenceRefs") or []:
|
||
if ref not in evidence_refs:
|
||
evidence_refs.append(str(ref))
|
||
return {
|
||
"ok": True,
|
||
"intent": name,
|
||
"power": power,
|
||
"requestId": request_id,
|
||
"actor": actor,
|
||
"data": {
|
||
"text": reply.text,
|
||
"blocks": blocks,
|
||
"commands": list(dumped.get("commands") or []),
|
||
"evidenceRefs": evidence_refs,
|
||
},
|
||
"interfaceVersion": INTERFACE_VERSION,
|
||
}
|