Repository navigation
V1 Safety and Evaluation
简体中文 | English
适用版本:v1.0.0。安全边界由可信应用和运行环境共同实施。模型输出、工具结果、检索结果、MCP 描述、Skill 指令和外部产物都不能自行授予权限。
| 层 | 入口 | 职责 |
|---|---|---|
| 业务身份与授权 |
SecurityContext、PermissionSet、CapabilityGate
|
绑定用户、租户、项目及资源。子任务只能收窄能力、风险、网络和截止时间。 |
| 组件与策略 |
CapabilityRegistry、CapabilitySpec、PolicyEngine
|
注册、选择和调用受信 Provider;声明 scope、读写、网络、风险、超时与审批需求。 |
| 生命周期 |
HookContext、HookDecision、PolicyHook
|
在指定阶段观察、改写或阻断;权限判定应在错误或超时时拒绝。 |
| 内容规则 | input/tool/output Guardrails | 输入、解析后的工具参数、最终非流式输出;不是 OS 沙箱。 |
| 人工核对 |
HumanApprovalHook、ApprovalDecision、ApprovalToken
|
核对实际操作;审批应过期、受范围约束,并要求可靠的审核人身份。 |
| 运行隔离 |
WorkspaceExecutionProvider、ExecutionRequirements
|
由执行环境实施,不能用提示词、签名或目录名代替。 |
ToolProviderAdapter、MemoryProviderAdapter、SkillProviderAdapter、MCPProviderAdapter、WorkflowProviderAdapter 可将现有组件接进注册表。选择最小能力集,按租户限制资源;同级冲突用 registry.conflicts() 诊断。授权应在实际调用边界再次检查,不只在模型选工具时检查。需要审批的 Capability 请求应使用绑定操作、参数、资源和身份的 ApprovalToken,而不是通用口令。
下面的权限服务用异常模拟不可用,PolicyHook 会在请求模型之前拒绝。代码故意使用本机占位端点,不需要密钥或真实服务:
from LightAgent import LightAgent, PolicyHook
def authorize(context):
raise RuntimeError("授权服务暂不可用")
agent = LightAgent(
name="policy-demo", model="offline-fixture", api_key="offline",
base_url="http://127.0.0.1:1/v1",
auto_discover_skills=False,
hooks=[PolicyHook(authorize, phases={"before_run"}, timeout=1.0)],
)
result = agent.run("读取示例数据", result_format="object", trace=True, max_retry=1)
assert result.error and "LA-HOOK" in result.error
print(result.error)普通观测 Hook 隔离自己的异常;策略必须显式选择 fail-closed 的 PolicyHook。阶段包括 run 前后及错误、模型请求与响应、工具前后、记忆读取/写入/晋升、Swarm handoff,以及 LightFlow 步骤、审批、resume/rerun。Codex 外部后端的策略阶段只支持 run 前后和错误,不观察 CLI 内部工具。调试时用 HookDecision.continue_()、replace() 或 block() 明确表达结果;不允许改写的阶段不能当作路由入口。
privacy_input_guardrail()、sensitive_tool_confirmation_guardrail()、high_risk_parameter_guardrail()、output_redaction_guardrail() 是可组合模板,不是自动合规方案。输出规则不能撤回已经流式发送的内容。旧任意 Python 工具不应暴露给不受信输入,模型与工具调度会阻止旧执行器;safe_expression 仅适合受限表达式。参考 Guardrails、Hooks 与配方。
给受保护的工具或 handoff 配置 HumanApprovalHook(store=..., tools={...})。没有同步审核人时,先生成待处理请求并阻止动作。可信审核端从 InMemoryReviewStore 或 JsonReviewStore 读取请求、校验实际参数,再调用 resolve(request_id, ApprovalDecision.approve(...));重跑对应动作时显式传 approval_id,不把内部审批标识传给模型。拒绝、编辑、批量处理和 HumanFeedback 由业务层挂接;格式见 人工审核。固定流程的持久审批示例见 LightFlow;后台任务交互见 持久执行。三类接口不应互换 ID。
要读取用量、按 token 估算费用或区分缺失数据,请先看用量统计与预算。
用 agent.run(..., result_format="object", trace=True) 读取 trace_id 与事件。常见事件包括 run 开始/结束、模型请求、工具调用/结果、审批、Hook 决策、Guardrail 阻断和错误;用 parent_trace_id / run_group_id 串联委托与子流程。用 agent.summarize_trace() 汇总延迟、重试、工具、审批和 token;JsonlTraceExporter 适合输出本地审计文件。原始工具参数和输出可能是敏感数据,对外导出前先脱敏并配置访问和保留策略。Langfuse 是可选 langfuse extra;本地 Trace 不要求 SDK。详见 Trace 参考 和 Langfuse 配置。
下面用稳定的本地 target 做一条不依赖模型的回归。应用可以换成真实 Agent、LightFlow 或测试替身,加上必须/禁止的工具、指定事件、延迟、恢复与业务断言。
from LightAgent import EvaluationCase, LightEvaluator, RunResult
class LocalTarget:
def run(self, query, **kwargs):
return RunResult(content="验收:" + query)
report = LightEvaluator().run(LocalTarget(), [
EvaluationCase(name="输出契约", query="数据格式", expected_output_contains=("验收", "数据格式"))
])
assert report.passed == 1
print(report.to_dict())用 评测参考 配置自定义断言和费用估算。费用估算不是账单,缺少 usage 不能推断没有产生费用。
安装 signing extra 后,在 v1.0.0 源码目录运行以下离线示例。它使用临时 Ed25519 密钥、审查指定摘要,演示修改后旧批准失效:
python example/17.signed_providers.py宿主从可信渠道配置发布者公钥;ProviderAttestation 绑定文件树、发布者、发行序号、版本、能力/配置摘要和有效期;ProviderTrustStore 保存明确批准和撤销;AttestedProvider 在启用和调用时核对。新内容和动态绑定发生变化需重新签名与批准,不能静默复用旧信任。签名不代替用户授权、运行隔离、操作审批,也不证明远端实现安全。演示密钥不用于生产。完整生命周期见 Provider 供应链与重授信。
LightAgent Wiki - see the repository, releases, and issues.
- Installation and Your First Agent
- Tools and Integrations
- Memory, Sessions, and RAG
- Workflows and Multiple Agents
- Agent Backends and Codex
- Durable Execution, Jobs, and Subagents
- Safety, Observability, and Evaluation
- Usage, Cost Estimates, and Budgets
- Deployment, Migration, and Verification
- 安装与第一个 Agent
- 工具和集成
- 记忆、会话与 RAG
- 工作流与多 Agent
- 执行后端与 Codex
- 持久执行、Jobs 与 Subagents
- 安全、观测与评测
- 用量统计、费用估算与预算
- 部署、升级与验收
- Quick Start
- Core Concepts
- API Reference
- Examples Cookbook
- Migration Guide
- Tools
- Tool Generator
- Memory
- MCP
- Skills
- LightFlow
- Tree of Thought
- Self-Learning
- Multi-Agent
- Tracing and Debugging
- Langfuse Observability
- Model Providers
- browser-use Integration
- Testing and CI
- Deployment Guide
- Architecture
- Security
- Known Limitations
- FAQ
- FAQ 中文
- Roadmap
- Release Process
- Contributing