使用 provider-neutral Harness 构建可靠的 LLM agents——涵盖 Agentic Loop、Tools & Permissions、Context Compaction、Security Evals，以及一个可直接使用的 Open-Source Skill。

AI agent 生态正在迅速爆发。从 customer support bots 到 financial analysis co-pilots，agents 承诺能够自动化复杂工作流。然而，大多数 agents 在 production 中失败，并不是因为底层 LLM 不够强，而是因为 harness（治理 agent 的 runtime wrapper）脆弱、不安全或不可预测。

在分析了数百个失败的 agent 部署案例后，一个清晰的模式浮现出来：缺失的关键环节是disciplined harness engineering。

这就是agents-best-practices的价值所在——一个 provider-neutral、production-ready skill，用于设计、审计和重构 agentic harnesses。该 open-source repository 由 Denis Sergeevitch 构建，灵感来自 Claude Code 和 Codex 的内部机制，为你提供从 component models 到 checklists 的具体 artefacts。它还遵循新兴的 Agent Skills standard，因此可以接入你常用的 AI-assisted environment。

👉 获取地址：https://github.com/DenisSergeevitch/agents-best-practices

在本文中，我们将拆解这个 repository，提炼 agent harness engineering 的核心原则，逐步讲解从 idea 到 production 的流程，并展示如何将你的 agent harness 部署到可靠的 infrastructure 上——还包括一个特别的 hosting bonus。

什么是 Agent Harness（以及为什么你需要它）？

Agent harness 是包裹 LLM 的 deterministic runtime layer。它会对 model 提出的每一个 action 进行 validation、authorisation、execution 和 logging。核心思想是明确的职责分离：

• Model 负责提出 actions 和 tool calls。
• Harness 负责执行它们——检查 schemas、permissions、budgets 和 safety rules。

如果没有合适的 harness，agents 就会变成黑盒：泄漏 tokens、陷入 uncontrolled loops，并执行危险命令。有了 harness，你就能获得 predictability、security 和 observability。

不可妥协的原则（来自 repository）

该 skill 定义了几条适用于任何domain 的硬性规则：

这些原则是 provider-neutral 的——它们适用于 OpenAI、Anthropic、open-source models，或任何未来的 LLM。

深入解析agents-best-practicesRepository

该 repository 遵循 Agent Skills specification：SKILL.md是入口点，详细 references 位于references/文件夹中。

Reference files 一览

为什么这不是“又一个 tips 列表”

大多数 blog posts 只会给出类似“validate tool inputs”的抽象建议。而这个 skill 提供的是 executable artefacts：

• 一个包含 15 个 modules 的 component model（instruction manager、context builder、model adapter、tool registry、permission resolver、budget tracker 等）
• 用 pseudocode 编写的 canonical agentic loop——包含 budgets、compaction triggers 和 stop conditions
• 一套 risk taxonomy（read_only、financial、destructive 等）和 permission matrix
• 一种 cache-aware ordering strategy，用于大幅降低 prompt caching 成本
• Security evals 不仅测试 model，还测试 harness 本身（injection、timeouts、over-tooling）

如果你是 ML engineer、platform architect 或 team lead，这个 skill 会改变你构建 agents 的方式。

Production-Ready Agents 的关键原则（从 skill 中提炼）

让我们聚焦最有影响力的原则。每一条都对应 production 中真实出现过的 failure mode。

1. Model proposes - harness executes

永远不要让 LLM 直接调用 tools。相反，model 应返回 structured tool call；harness 负责验证 schema、检查 permissions、执行操作，并将结果注入回上下文。这可以防止 prompt injection 升级为 arbitrary code execution。

2. 每次 tool call 都必须返回 result——即使失败

无论是成功的 API response、permission denial，还是 timeout，agent 都应始终收到 structured observation。不能留下 dangling promises。

3. Risk 会改变流程

至少使用三个 risk levels：

• Read-only（autonomous）
• Draft（internal simulation，无 external side effects）
• External write（requires approval）

这就是 draft-commit pattern——危险 actions 先被 drafted，然后再显式 committed。

4. Context 是 assembled，而不是 dumped

不要把完整 conversation history 塞进每一轮。使用分层结构：

• Policies（system-level，很少变化）
• Scoped instructions（per-task 或 per-domain）
• Runtime hints（从 memory 或 tools 中 JIT-retrieved）

为 untrusted data（例如 user input）标记 trust label，这样 harness 就能对其进行差异化处理。

5. Long tasks 必须有 budgets

每个 agent loop 都必须具备：

• Step budget（最大迭代次数）
• Time budget（wall-clock）
• Token budget（per turn 和 cumulative）
• Cost budget（USD limit）

当 budget 耗尽时，harness 应优雅终止，并返回 structured failure。

6. 反复出现的 failures 应变成 harness features

如果你的 agent 反复失败，是因为某个 tool 返回 malformed response，不要在 prompt 里修补——应该在 harness 中编写 validator function。如果 agent 每次都询问同一类缺失信息，就构建一个 tool 自动检索它。

Step-by-Step Guide：使用该 Skill 从 Idea 到 Production

该 repository 提供了具体方法论：Map → Identify → Blueprint → Implement → Launch。

Phase 1：Map（提出正确问题）

在编写任何代码之前，先回答：

• 什么 domain？（customer support、finance、DevOps 等）
• 什么 autonomy level？（Level 0 = human does everything，Level 4 = fully autonomous）
• 什么 risk level？（read-only、financial、destructive）
• 哪些 external systems？（Slack、Linear、Drive、databases、APIs）

Phase 2：Identify（选择 MVP level）

根据你的回答，从mvp-agent-blueprint.md表格中选择一个 MVP level。对大多数首次构建 agents 的团队来说，Level 1（每次 external write 都由 human approval）或 Level 2（plans 由 human-approved，low-risk steps 可 autonomous execution）是最佳起点。

Phase 3：Blueprint（生成 harness design）

现在让 skill 生成 blueprint。你只需向已安装该 skill 的 AI assistant 描述你的 domain。输出将包括：

• Goal 和 domain boundaries
• Agentic loop（stop conditions、budgets）
• Tool registry（每个 tool 都包含 typed schema 和 risk class）
• Permission matrix（谁可以在什么情况下调用什么，何时需要 approval）
• Context & memory layering（哪些保留在 cache 中，哪些 JIT-fetched）
• Skills & connectors（使用哪些 Agent Skills 或 MCP servers）

Phase 4：Implement（严格遵循 blueprint）

严格在描述的边界内构建 MVP。先从 skeleton 和 validation path 开始，然后逐步加入经过衡量的扩展。checklists.md文件提供了逐行 implementation checklist。

Phase 5：Launch（上线前审计）

进入 production 前，运行checklists.md中的 audit checklists。确认：

• Budgets 已强制执行
• Permissions 正确（没有execute_anythingtools）
• Injection 和 timeouts evals 通过
• Observability（traces、logs）已就位

真实案例：Contract risk analysis agent

使用该 skill，一个团队构建了一个 agent，它可以：

• 读取 contract drafts（read-only，autonomous）
• 生成 risk brief 和 draft actions（draft mode）
• 仅在 explicit approval 后发送 emails（external write，requires approval）

Harness blueprint 在 15 分钟内生成，implementation 用了两天，该 agent 已运行六个月，期间没有发生任何 unauthorised actions。

案例：审计现有 research agent

在审计一个失败的 agent 时，该 skill 揭示了：

• 没有 hard budgets → agent loop 运行超过 200 步
• Context compaction 擦除了 active approvals → agent 丢失 state
• 没有 injection evals → user 可以诱导 agent 删除 files

该 skill 提供了 step-by-step remediation plan：添加 budgets、修复 compaction ordering，并编写三个 security evals。

Practical Implementation Tips（含 pseudocode）

Canonical agentic loop（简化版）

python

budgets = Budgets(step=25, time=120, tokens=8000, cost=0.50) context = build_initial_context() permissions = load_permission_matrix()while not budgets.exhausted(): response = model.generate(context, tools=typed_tool_schemas) if response.finish_reason == "stop": break if response.tool_calls: for tool_call in response.tool_calls: if not permissions.is_allowed(tool_call): observation = "Permission denied: " + tool_call.name else: # Execute with risk‑appropriate checks if permissions.risk(tool_call) == "external_write": approval = request_human_approval(tool_call.draft) if not approval: observation = "Human rejected: " + tool_call.name else: observation = execute_tool(tool_call) else: observation = execute_tool(tool_call) context.append(observation) # Optional compaction trigger if context.token_count() > budgets.token_per_turn: context = compact_context(context, preserve_approvals=True) else: # No tool calls, just final answer break

Tools：从 bad 到 good

该 skill 的tools-and-permissions.md提供了完整 taxonomy 和可直接复制的 permission matrix。

面向 cache efficiency 的 context layering

text

Layer 0: System policies (stable prefix) → Cached Layer 1: Agent skill definitions (rarely change) → Cached Layer 2: User session instructions (per conversation) → Not cached Layer 3: JIT‑retrieved tool outputs (fresh) → Not cached

通过按照从最稳定到最不稳定的顺序排列 layers，你可以最大化 prompt caching 并降低成本。prompt-caching-and-cost.md文件详细展示了如何使用 deterministic serialisation 实现 cache-aware ordering。

部署你的 Agent Harness：为什么 Infrastructure 很重要

你已经构建了一个 robust harness——很好。但它要运行在哪里？Agent harnesses 对 latency 敏感，并且具有 stateful 特性。它们需要：

• Low-latency compute（LLM API calls + local validation）
• DDoS protection（agents 通常是 public-facing endpoints）
• Reliable uptime（production agents 不能宕机）
• Flexible scaling（从 MVP 扩展到数百万请求）

这就是 Aeza 的用武之地。

Aeza 是一家现代 cloud hosting provider，于 2021 年 12 月推出，专注于 VPS/VDS 和 dedicated servers，并内置 DDoS protection。其 infrastructure 非常适合运行 agent harnesses——无论你托管的是轻量级 Python loop，还是分布式 agent swarm。

为什么 agent workloads 适合用 Aeza？

• 多地区 low-latency VPS——最小化到 LLM APIs 的 round-trip time。
• Automatic DDoS protection——因为 agents 经常成为 prompt injection attacks 的目标，攻击者会试图耗尽资源。
• Flexible configurations——从小型 VPS 测试起步，再升级到 production 级 dedicated metal。
• Developer-friendly——没有隐藏 quotas，提供 full root access，支持 Docker 和 Kubernetes。

👉 读者特别优惠：通过 我的 Aeza referral link 注册后，你将在注册后的前 24 小时获得 15% bonus。使用这部分额外额度启动 VPS，部署你的 agent harness，并在真实负载下进行测试。

我已经在多个 agent deployments 中使用 Aeza——raw performance、DDoS protection 和 transparent pricing 的组合，使它成为欧洲 providers 中一颗被低估的宝石。

Security、Observability 和 Evals（不要跳过）

该 repository 的security-evals-observability.md非常有价值。它提供：

• Agent harnesses 的 threat model（injection、denial-of-service、tool abuse、approval spoofing）
• Multi-level guardrails（input sanitisation、permission checks、output validation）
• Tracing format（每一步：prompt、tool call、observation、latency、cost）
• 针对 harness 本身的 evals——不只是 model accuracy：
• Injection resistance：user prompt 是否能覆盖 system instructions？
• Timeout resilience：当 tool 卡住时，harness 是否会停止？
• Over-tooling：agent 是否请求了不必要的 tools？

上线前运行这些 evals。该 skill 包含 ready-to-use test cases。

Conclusion and Next Steps

agents-best-practicesrepository 是一份 practical、deep、provider-neutral 的指南，用于构建 production-grade agent harnesses。它不是抽象理论，而是一组具体 artefacts：component models、pseudocode、checklists 和 security evals。

无论你是：

• 构建下一代 autonomous agents 的 ML engineer，
• 设计 skill delivery 和 MCP infrastructure 的 platform architect，
• 审计现有 agent codebases 的 team lead，
• 或是在 model 外部实现 guardrails 的 security/compliance specialist，

……这个 skill 都能帮你节省数月试错时间。

Your immediate action plan

1. 安装该 skill

npx skills add DenisSergeevitch/agents-best-practices -g

或手动 clone：

git clone https://github.com/DenisSergeevitch/agents-best-practices.git ~/.codex/skills/

2. 阅读SKILL.md，并选择一个与你当前痛点匹配的 reference file（例如，如果你的 agent 一直运行不停，就看agentic-loop.md）。

3. 为你的 domain 生成 blueprint——让你的 AI assistant（Claude Code、Codex 等）使用该 skill，并生成 harness design。

4. 将你的 harness 部署到可靠的 infrastructure 上。可以试试 Aeza，它提供 low-latency、DDoS-protected VPS——通过 我的链接 注册时，别忘了领取首日 15% bonus。

5. 分享你的经验——在 GitHub repo 上提交 issue 或 PR。我们使用这些 patterns 构建的 production harnesses 越多，整个生态就会变得越好。

脆弱、不可预测 agents 的时代正在结束。通过 disciplined harness engineering，我们可以构建安全、可靠且 cost-effective 的 AI agents——并且能够扩展到任何规模。

这里给大家精心整理了一份全面的AI大模型学习资源，包括：AI大模型全套学习路线图（从入门到实战）、精品AI大模型学习书籍手册、视频教程、实战学习、面试题等，资料免费分享！

👇👇扫码免费领取全部内容👇👇

1. 成长路线图&学习规划

要学习一门新的技术，作为新手一定要先学习成长路线图，方向不对，努力白费。

这里，我们为新手和想要进一步提升的专业人士准备了一份详细的学习成长路线图和规划。可以说是最科学最系统的学习成长路线。

2. 大模型经典PDF书籍

书籍和学习文档资料是学习大模型过程中必不可少的，我们精选了一系列深入探讨大模型技术的书籍和学习文档，它们由领域内的顶尖专家撰写，内容全面、深入、详尽，为你学习大模型提供坚实的理论基础。（书籍含电子版PDF）

3. 大模型视频教程

对于很多自学或者没有基础的同学来说，书籍这些纯文字类的学习教材会觉得比较晦涩难以理解，因此，我们提供了丰富的大模型视频教程，以动态、形象的方式展示技术概念，帮助你更快、更轻松地掌握核心知识。

4. 2026行业报告

行业分析主要包括对不同行业的现状、趋势、问题、机会等进行系统地调研和评估，以了解哪些行业更适合引入大模型的技术和应用，以及在哪些方面可以发挥大模型的优势。

5. 大模型项目实战

学以致用，当你的理论知识积累到一定程度，就需要通过项目实战，在实际操作中检验和巩固你所学到的知识，同时为你找工作和职业发展打下坚实的基础。

6. 大模型面试题

面试不仅是技术的较量，更需要充分的准备。

在你已经掌握了大模型技术之后，就需要开始准备面试，我们将提供精心整理的大模型面试题库，涵盖当前面试中可能遇到的各种技术问题，让你在面试中游刃有余。

7. 资料领取：全套内容免费抱走，学 AI 不用再找第二份

不管你是 0 基础想入门 AI 大模型，还是有基础想冲刺大厂、了解行业趋势，这份资料都能满足你！
现在只需按照提示操作，就能免费领取：

👇👇扫码免费领取全部内容👇👇