Six Core Principles for Building Reliable AI Agent Systems

Three Core Principles for Building Effective Agents

Start with the simplest solution and add complexity only when necessary. Direct API calls are preferable to complex frameworks. Task orchestration should follow an evolutionary path: single LLM call → deterministic workflow → single agent → multi-agent , avoiding premature complexity that incurs high latency and token costs.

Maintain transparency: Explicitly show the agent's planning steps, execution logs, and decision traces to facilitate debugging and build user trust.

Design tool interfaces (ACI) from the agent's perspective: Interfaces should be intuitive for the agent to understand and use, not just for programmers. Tool names and parameters must be clear; error-prone designs should be eliminated through "fool-proof" design to prevent ambiguous interfaces from amplifying systemic errors.

General Harness Principles

Constraints over guidance: Enforce rules via code or system mechanisms (e.g., type constraints, CI checks) rather than relying on natural language documentation or prompt suggestions.

Automate validation: Depend on test suites and automated checks to eliminate the scaling bottleneck of manual review.

Faster, more structured feedback: Detailed error information provided close to the moment of occurrence improves the agent's correction efficiency (e.g., via an agent status bar with detailed context and counters).

Reliable rollback: Use sandbox, branching, or snapshot mechanisms to ensure trial-and-error is reversible.

Tool (ACI) Design Principles

Combine general and specialized tools: General base capabilities support composition and exploration; high-risk or strongly business-constrained operations (payments, data deletion, email sending) must be encapsulated as specialized tools with explicit parameters, restricted permissions, and auditability.

Structured returns and pagination: Search tools should return structured candidate lists (title, summary) rather than dumping full content; support pagination/cursors so the agent decides whether to read deeper.

Explicit truncation and on-demand reading: File/data reading tools must support offset/limit; when truncation thresholds are reached, explicitly indicate the omitted amount and how to continue reading — silent truncation that causes misjudgment is forbidden.

Leverage read-only advantages: Perception/read-only tools should actively use safe caching and concurrent execution to improve efficiency.

Context and Prompt Engineering Principles

KV Cache-friendly context layout: Keep static prefixes (system prompt, tool definitions) byte-level stable; once determined, avoid dynamic modifications. Dynamic tool information should always be appended to the end.

Explicit and structured knowledge: Surface implicit state (retry/call counts, task phases) as explicit metadata (e.g., an "agent status bar") at the end of the context to guide attention and reduce model recomputation overhead.

On-demand context loading (Skills mechanism): Separate metadata catalog from full instructions; present the catalog first, inject full instructions only when selected, optimizing context cost.

Explicit context compression retention priorities: When compressing, fully preserve "architectural decisions and key constraints", "modified files and change records", "verification status (pass/fail)", and "unresolved TODOs"; intermediate tool outputs retain only conclusions.

Align with model vendor training methodologies: Prefer interaction paradigms that the base model was specifically trained to follow.

Evaluation and Continuous Evolution Principles

No evaluation, no improvement: The evaluation target is the combined "model + harness" system. Use systematic experiments and ablation studies to distinguish model capabilities from engineering defects.

Progressive information disclosure in human-AI evaluation: When simulating real users, do not expose all requirements at once; reveal them gradually during the conversation to test the agent's proactive clarification ability.

Distinguish mechanism metrics from target metrics: Do not mistake process changes (mechanism metrics, e.g., plan length) for ultimate optimization goals (target metrics, e.g., session cost). Establish guardrail metrics that must not be crossed.

Built-in privacy: Embed privacy and security constraints into data collection and evaluation mechanisms from the start.

Minimum updates and falsifiable contracts: Continuous evolution should not blindly stack prompts. Instead, propose minimal changes based on failure evidence, validate via regression tests, controlled experiments, and canary releases before merging.

Multi-Agent Collaboration and Architecture Principles

Decide based on information increment and ROI: Adopt multi-agent only when it brings external new information unattainable by a single agent (execution feedback, cross-modal vision, independent verification) and the benefit covers the additional token cost.

Specialized division of labor and context isolation: Build specialized sub-agents rather than a generalist agent. Pass information via structured handoff packages or protocols to avoid global context bloat and cognitive inertia.

Sub-agent prompt specifications: Clear role definitions, explicit input source annotations (to prevent prompt injection), strict task boundaries, standardized output formats.

Explicit termination and fault tolerance controls: Establish dynamic step budget allocation, event-stream-based cascade termination mechanisms, optimistic locking isolation, and human-in-the-loop (HITL) timeout fallback strategies.

Source: https://github.com/bojieli/ai-agent-book (from the book "Deep Understanding of Agent")