ai-agent-design
Comprehensive guide to designing, building, and operating AI agents. Covers agent architecture, tool use patterns, memory systems, orchestration strategies, planning approaches, error recovery, and safety guardrails for production-grade agent systems.
cosmicstack-labs · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add cosmicstack-labs/mercury-agent-skills --skill ai-agent-design技能说明
name: ai-agent-design description: Comprehensive guide to designing, building, and operating AI agents. Covers agent architecture, tool use patterns, memory systems, orchestration strategies, planning approaches, error recovery, and safety guardrails for production-grade agent systems. metadata: author: cosmicstack-labs version: 1.0.0 category: ai-ml tags: - ai-agents - agent-architecture - tool-use - memory-systems - orchestration - planning - llm
AI Agent Design
Core Principles
1. Agents Are Tools, Not Teammates
An AI agent is a system that uses an LLM to reason and take actions. It is not a person — it has no goals, desires, or understanding. Design agents as tools with clear boundaries, not as autonomous collaborators.
2. Autonomy is a Spectrum
Full autonomy is rarely the goal. The best agents operate on a spectrum: more human oversight for critical actions, more autonomy for routine tasks. Design for the level of autonomy that matches the risk.
3. Cache Everything, Guess Nothing
Agents have no memory between calls unless you design it. Every interaction, tool result, and decision must be explicitly stored and retrieved. Assume the agent remembers nothing unless you program it to.
4. Fail Predictably
Every agent will fail. The question is how it fails. Design for graceful degradation: when uncertain, ask for help. When stuck, escalate. When broken, stop safely.
5. Safety First, Speed Second
A fast agent that takes unauthorized actions is worse than a slow agent that double-checks. Build guardrails before building features.
Agent Maturity Model
| Level | Name | Characteristics | Tool Use | Memory | Autonomy |
|---|---|---|---|---|---|
| L1 | Reactive | Single-turn, no context retention, deterministic responses | None or hardcoded | None | None |
| L2 | Scripted | Pre-defined workflows, conditional branching, template-based | Basic function calls with fixed signatures | Session-only (ephemeral) | Low — requires human confirmation |
| L3 | Tool-Using | Dynamic tool selection, structured function calling, error handling | Multiple tools, runtime discovery | Short-term (conversation history) | Medium — executes routine tasks autonomously |
| L4 | Memory-Augmented | Long-term memory, learns from past interactions, personalization | Complex tools with parameter binding | Long-term + episodic (vector stores, databases) | High — manages complex workflows |
| L5 | Autonomous Orchestrator | Multi-agent coordination, dynamic planning, self-correction, meta-cognition | Tool composition, tool creation, delegation | Semantic + episodic (knowledge graphs, RAG) | Full — handles novel situations independently |
Progression Path
- L1 → L2: Add conditional logic and basic state tracking
- L2 → L3: Implement tool schemas and function calling
- L3 → L4: Integrate persistent storage and retrieval mechanisms
- L4 → L5: Add planning, sub-agent delegation, and self-evaluation
Tool Definition Patterns
Function Calling / Tool Use
Modern LLMs support "function calling" — the model outputs a structured request to invoke a tool, and the runtime executes it and returns the result.
Tool Schema Pattern (OpenAI-style)
{
"type": "function",
"function": {
"name": "search_knowledge_base",
"description": "Search the internal knowledge base for relevant documents",
"parameters": {
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "The search query string"
},
"max_results": {
"type": "integer",
"description": "Maximum number of results to return (1-20)",
"minimum": 1,
"maximum": 20
},
"filter_by_date": {
"type": "string",
"description": "Optional date filter in ISO 8601 format"
}
},
"required": ["query"]
}
}
}
Tool Definition Best Practices
- Descriptions are critical: The model reads tool descriptions to decide what to call. Be explicit about when to use each tool.
- Validate parameters: Use JSON Schema constraints (minimum, maximum, enum, pattern) to prevent invalid calls.
- Return structured data: Tool results should return structured data (JSON) so the model can reason about them.
- Include error information: If a tool fails, return a clear error message the model can act on.
Tool Implementation Pattern (Python)
from typing import Any
import json
class AgentTool:
"""Base class for agent tools."""
def __init__(self, name: str, description: str):
self.name = name
self.description = description
def get_schema(self) -> dict:
"""Return the function calling schema for this tool."""
raise NotImplementedError
async def execute(self, **kwargs) -> Any:
"""Execute the tool with validated parameters."""
raise NotImplementedError
class SearchTool(AgentTool):
def __init__(self):
super().__init__(
name="search",
description="Search documents by query string"
)
def get_schema(self):
return {
"type": "function",
"function": {
"name": self.name,
"description": self.description,
"parameters": {
"type": "object",
"properties": {
"query": {"type": "string"},
"limit": {"type": "integer", "default": 5}
},
"required": ["query"]
}
}
}
async def execute(self, query: str, limit: int = 5):
# Implementation
results = await database.search(query, limit=limit)
return json.dumps({"results": results, "count": len(resul
阅读完整来源 ↗