This server exposes a governed enterprise agent over MCP, letting you search company knowledge and safely run or approve business tasks.
search_enterprise_policy: Search enterprise policies with hybrid retrieval (e.g., expense, leave, compliance rules).
search_enterprise_docs: Search enterprise handbooks and runbooks for procedures and troubleshooting guidance.
run_enterprise_agent: Run a governed agent task with user/role binding; low-risk actions execute directly, while high-risk actions return an approval id instead of executing.
decide_enterprise_approval: Managers/admins can approve or reject pending high-risk operations, optionally with a comment.
Supported tasks include enterprise knowledge Q&A, evidence-driven investigations, P1 ticket creation/approval, and retrieval of investigation reports and execution traces.
All actions pass through governance: RBAC, human approval, rate limiting, duplicate protection, output budgeting, idempotent writes, and full audit tracing.
Integrates with OpenAI Responses API to provide dynamic tool selection and planning for the agent loop, enabling online model-driven planning while preserving deterministic policy enforcement and approval controls.
Integrates SQLite as the persistent storage backend for sessions, messages, summaries, approvals, tickets, and execution traces, supporting resumable approvals and auditable agent workflows across process restarts.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@enterprise-agent-mcp 查询 P1 审批制度并创建 P1 工单：生产 API 大面积超时"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
EnterpriseOps Agent 是一个面向企业知识问答、事件调查和受控业务执行的 Agent 服务。项目将通用 Agent 能力与企业级治理结合：模型负责规划和工具选择，确定性执行层负责身份、权限、审批、限流、幂等、副作用和审计。
默认 demo 模式不需要 API Key，可以完成全流程演示和测试；切换到 openai 模式后，使用 OpenAI Responses API 进行动态工具调用。
通用 Agent 内核：OpenAI Responses Tool Calling、最大步数 Agent Loop、工具 JSON Schema、会话记忆和确定性离线规划器。
多入口复用：FastAPI REST、CLI 和 MCP Server 共享同一个 Agent Engine 与工具治理层。
混合 RAG：面向中文制度、员工手册和 Runbook，融合关键词重叠与 256 维确定性向量相似度。
能力化工具注册：工具声明 read/write/destructive 类型、确认策略、能力标签和输出预算，模型无法自行扩大权限。
企业工具治理链：身份绑定、RBAC、HITL、超时、全生命周期审计、用户/工具级限流、重复调用防护、输出裁剪和写操作幂等。
证据驱动调查：先分诊，再调用 Runbook、历史工单和制度调查角色，统一生成带引用、推理、排除项、证据强度和证据缺口的结构化报告。
持久化恢复：SQLite WAL 保存会话、消息、摘要、审批、工单、调查报告、工具执行状态和 Trace；审批后使用稳定幂等键恢复写操作。
可观测与评测：记录规划、策略、审批、工具开始/成功/失败/超时、调查 Findings 和综合结果；配套单元/集成测试与离线行为评测。
Related MCP server: agent-mcp-workflow-platform
flowchart TD
Client[REST / CLI / MCP] --> Engine[Agent Engine]
Engine --> Triage{请求分诊}
Triage -->|知识问答/业务任务| Planner[Demo / OpenAI Planner]
Planner --> Loop[Agent Tool Loop]
Triage -->|事件调查| Dispatch[Capability Dispatcher]
Dispatch --> Runbook[Runbook Investigator]
Dispatch --> History[Ticket History Investigator]
Dispatch --> PolicyAgent[Policy Investigator]
Runbook --> Findings[Structured Findings]
History --> Findings
PolicyAgent --> Findings
Findings --> Synthesis[Evidence-grounded Synthesis]
Loop --> Runtime[Governed Tool Runtime]
Runbook --> Runtime
History --> Runtime
PolicyAgent --> Runtime
Runtime --> Chain[Identity → RBAC → HITL → Timeout → Audit → Rate Limit → Repeat Guard → Output Budget → Idempotency]
Chain --> Tools[Enterprise Tools / RAG]
Tools --> DB[(SQLite WAL)]
Synthesis --> DB所有工具入口都经过 ToolRuntime，而不是在 Prompt 中约定安全规则。即使模型伪造 creator_id、调用未授权写工具或重复触发已审批操作，执行层仍会绑定可信身份、进行权限判断并控制副作用。
对“排查 API 延迟异常”一类请求，系统执行以下流程：
Triage 根据请求信号和已注册工具能力选择调查角色，最多分派三个调查器。
每个调查器只调用其能力范围内的只读工具，并把不同工具结果转换为统一 Evidence。
每个分支输出 Finding，必须包含状态、摘要、推理、证据 ID、排除项和自评强度。
Synthesis 只允许引用 Findings 中实际存在的证据，同时明确置信度和证据缺口。
完整 InvestigationReport 按 trace_id 持久化，可通过 API 复查。
结构化报告不会把用户输入或模型常识冒充成现场证据。当系统只有 Runbook、没有实时指标和日志时，会明确输出“尚不能确认具体根因”。
Identity Binding
→ Authorization (RBAC + risk policy)
→ Human Approval Gate
→ Timeout
→ Audit Start/End
→ Per-user/Per-tool Rate Limit
→ Duplicate Read Guard
→ Output Budget
→ Idempotent Write Execution
→ Tool Handler关键约束：
employee/manager/admin 三级 RBAC 在服务端执行，未注册策略默认拒绝。
P1 工单和敏感更新在写入前持久化审批请求；拒绝不会产生业务副作用。
审批恢复使用 approval:{approval_id} 作为稳定幂等键，相同写操作只返回首次结果，不会重复创建工单。
完全相同的只读调用在同一 Agent 运行中只执行一次，防止模型陷入无效循环。
超大结果保留原始业务值，但只向模型上下文注入受限预览，降低上下文膨胀风险。
限流拒绝、工具异常和超时也会进入审计 Trace；写工具超时时以 outcome=unknown 标记，禁止盲目重试。
enterprise-agent/
├─ src/enterprise_agent/
│ ├─ engine.py # 通用 Agent Loop、审批暂停/恢复
│ ├─ orchestrator.py # Triage、调查角色、Findings、Synthesis
│ ├─ governance.py # 可组合工具治理中间件与统一执行入口
│ ├─ planner.py # Demo/OpenAI 双规划器
│ ├─ tools.py # 工具元数据、Schema 和业务处理器
│ ├─ policy.py # RBAC 与风险策略
│ ├─ retrieval.py # 混合 RAG
│ ├─ database.py # SQLite Schema、事务和持久化
│ ├─ api.py # FastAPI API
│ ├─ mcp_server.py # MCP Server
│ └─ models.py # Pydantic 领域模型
├─ data/knowledge.json
├─ tests/
├─ evals/
├─ docs/TECHNICAL_HIGHLIGHTS.md
├─ Dockerfile
└─ docker-compose.yml要求 Python 3.11+。
cd "C:\Users\Lenovo\Desktop\agent开发准备\enterprise-agent"
python -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -e ".[dev]"
Copy-Item .env.example .env# 知识问答
enterprise-agent "差旅报销超过 5000 元有什么规定？"
# 多路径调查
enterprise-agent "排查 API 延迟超过 2 秒的根因，并参考历史工单"
# 持久化审批与恢复
enterprise-agent "查询制度并创建 P1 工单：生产 API 大面积超时" --approve-as u-2001uvicorn enterprise_agent.api:app --reload --port 8000Swagger：http://localhost:8000/docs
能力和治理元数据：GET /v1/capabilities
创建会话：POST /v1/sessions
执行任务：POST /v1/sessions/{session_id}/messages
审批决策：POST /v1/approvals/{approval_id}/decision
调查报告：GET /v1/investigations/{trace_id}
执行轨迹：GET /v1/traces/{trace_id}
工单查询：GET /v1/tickets
生产环境应设置 APP_ENV=production 并更换 API_KEY。真实部署建议在 API Gateway 接入 OIDC/SSO，由可信令牌提供用户和角色，而不是将示例 API Key 作为最终用户认证方案。
AGENT_MODE=openai
OPENAI_API_KEY=sk-...
OPENAI_MODEL=gpt-4.1-mini模型只负责规划、工具选择和参数生成；身份绑定、审批、限流、幂等和写副作用始终由服务端代码控制。
enterprise-agent-mcpMCP 暴露企业知识检索、受治理 Agent 执行和审批决策。MCP 与 REST 使用同一个 AgentEngine，不能绕开高风险操作审批。
Copy-Item .env.example .env
docker compose up --buildpytest -q
python evals/run.py
ruff check src tests当前回归结果：
自动化测试：19 项通过。
离线行为评测：6/6 通过。
覆盖范围：RAG 命中、P1 审批通过/拒绝、越权审批、角色冒充、治理 Trace、结构化调查、报告持久化、身份强绑定、数据隔离、写操作幂等、限流和 API 契约。
当前仓库适合本地演示、架构验证和二次开发。正式部署时建议：
SQLite 替换为 PostgreSQL，限流器替换为 Redis，以支持多实例一致性。
RAG 替换为 pgvector、Milvus 或 Elasticsearch，并增加文档分块和增量索引。
接入 Prometheus、Loki、Tempo、Jira 或 ServiceNow，优先开放只读工具，写工具使用最小权限凭证。
将 Trace 导出到 OpenTelemetry 后端，并增加 Token、延迟、工具成功率和审批等待时间指标。
外部连接器必须设置自己的网络超时与重试策略；写操作必须携带幂等键或采用 outbox/补偿事务。
详细的架构取舍和简历表述见 docs/TECHNICAL_HIGHLIGHTS.md。
Approve or reject a pending high-risk operation as a manager/admin.
| Name | Required | Description | Default |
|---|---|---|---|
| comment | No | ||
| approved | Yes | ||
| approval_id | Yes | ||
| reviewer_id | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It signals a consequential decision ('high-risk operation') but never says whether the action is irreversible, what state change approve vs reject produces, whether decisions can be revoked, or how authorization is verified.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence with the verb front-loaded and no filler. It is efficient, though arguably too terse for a destructive decision tool with four parameters.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A mutating, authorization-gated tool with no annotations, no output schema, and four undocumented parameters needs substantially more than one sentence. The description does not cover return behavior, error/permission cases, or parameter requirements.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description documents none of the four parameters. The boolean `approved` and `reviewer_id` can be loosely inferred from 'approve or reject' and 'as a manager/admin', but `approval_id` and `comment` are entirely unexplained, including whether comment is required on rejection.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb pair (approve/reject) and a clear resource (pending high-risk operation), plus a role constraint (manager/admin). No sibling tool overlaps this approval domain, so sibling differentiation is not needed, but the description does not name it as the only decision tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It implies when to use it by stating the object is a 'pending high-risk operation' and the caller must be a manager/admin. There is no explicit when-not guidance, no statement of prerequisites such as where the approval_id comes from, and no named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Run the governed Agent. High-risk actions return an approval id and never execute directly.
| Name | Required | Description | Default |
|---|---|---|---|
| role | No | employee | |
| message | Yes | ||
| user_id | No | u-1001 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose one genuinely important non-obvious trait: high-risk actions return an approval id and never execute directly. However, it omits other behavior an agent needs, such as what happens for low-risk actions, permission/role effects, and the return shape.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, the safety-relevant trait is front-loaded after the core purpose, and there is no filler. Everything present earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter agent-invocation tool with no annotations and no output schema, the description is thin: it does not explain parameter meaning, valid role values, return contents, or how it relates to the decide_enterprise_approval sibling. Only the approval-gating behavior is covered.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the description adds nothing about the three parameters (role, message, user_id). An agent gets no explanation of what role values are valid, how user_id is used, or what message should contain, so the description fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb+resource combo ('Run the governed Agent'), which clearly separates it from the search/decide siblings. It is clear but does not explicitly name which sibling to prefer for what task, keeping it short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no when-to-use guidance, no prerequisites, and no routing between this tool and siblings like search_enterprise_policy or decide_enterprise_approval. The approval flow implies a relationship with decide_enterprise_approval, but that link is left entirely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search enterprise handbooks and runbooks.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, and it says nothing about read-only semantics, result ranking, pagination, or scope limits. 'Search' implies a non-destructive read, but no explicit trait beyond that is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short sentence with zero filler, and the scope (handbooks and runbooks) is front-loaded. It is efficient, though its brevity partly reflects under-specification rather than disciplined editing.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be described, and complexity is low with one required parameter. However, with no annotations and no query guidance, the definition leaves an agent unable to judge result behavior or query formulation for a search tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% for the single required 'query' parameter, and the description adds no syntax, format, or matching guidance. The only implicit meaning is that the query targets handbook/runbook content, which barely compensates for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a clear verb and resource ('Search enterprise handbooks and runbooks'), which tells the agent exactly what content this tool queries. It implicitly distinguishes itself from the sibling search_enterprise_policy by naming a different document set, though it never calls out that sibling explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no prerequisites, and no routing to or away from alternatives. The agent must infer from the document types alone whether handbooks/runbooks or policies are the right target for a given query.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search enterprise policies with hybrid retrieval.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden. 'Hybrid retrieval' hints at a combined semantic/keyword search but gives no detail on ranking, result limits, coverage, or permissions. For a search tool with zero annotation coverage, this is thin.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single short, front-loaded sentence with no wasted words. Its brevity borders on under-specification, but the structure itself is clean and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists and return values need not be explained, the definition omits query semantics and any routing guidance against the near-identical search_enterprise_docs sibling. For a search tool with no annotations, these omissions leave the agent under-informed.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single required parameter 'query' has 0% schema description coverage and the description says nothing about its expected form, syntax, or natural-language behavior. With the schema providing no semantics, the description should compensate and does not.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a verb and resource ('Search enterprise policies'), so the basic operation is clear. However, it does not differentiate this tool from the very similar sibling search_enterprise_docs, and 'hybrid retrieval' describes mechanism rather than scope. It largely restates the tool name with a mechanism tag.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no statement of when to use this tool versus the close sibling search_enterprise_docs, nor any exclusion or prerequisite. The agent must infer the distinction from the names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0decide_enterprise_approvalrun_enterprise_agentsearch_enterprise_docssearch_enterprise_policyScored across 4 tools
search_enterprise_policy and search_enterprise_docs both perform hybrid retrieval over enterprise content and differ only by content type (policies vs handbooks/runbooks), which an agent could easily confuse. The run/decide pair is clearly distinct, but the two search tools create meaningful overlap.
All four tools use consistent snake_case verb_noun structure with a shared 'enterprise' infix (search_enterprise_policy, search_enterprise_docs, run_enterprise_agent, decide_enterprise_approval), making the pattern highly predictable.
Four tools is on the thin side for a governed-agent workflow, and since the two search tools largely overlap, the effective surface is even smaller. It is not egregiously sparse but feels borderline for the stated scope.
The run/approve lifecycle is covered, but there is no tool to list or fetch pending approvals, so an agent receiving an approval id has no way to discover or inspect outstanding approval requests. Retrieval also lacks any get-by-id or fetch operation.
Governed MCP gateway: one endpoint for your tools, with credential custody and audit log.
MCP server for mandates, delegation, policy-gated execution, credential grants, and audit.
Governed data discovery, exact queries, decisions, simulations, and runtime utilities over MCP.
Authenticated MCP server for ClearPolicy policy and compliance workflows.
