跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
设计与 UI

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

LevelNameCharacteristicsTool UseMemoryAutonomy
L1ReactiveSingle-turn, no context retention, deterministic responsesNone or hardcodedNoneNone
L2ScriptedPre-defined workflows, conditional branching, template-basedBasic function calls with fixed signaturesSession-only (ephemeral)Low — requires human confirmation
L3Tool-UsingDynamic tool selection, structured function calling, error handlingMultiple tools, runtime discoveryShort-term (conversation history)Medium — executes routine tasks autonomously
L4Memory-AugmentedLong-term memory, learns from past interactions, personalizationComplex tools with parameter bindingLong-term + episodic (vector stores, databases)High — manages complex workflows
L5Autonomous OrchestratorMulti-agent coordination, dynamic planning, self-correction, meta-cognitionTool composition, tool creation, delegationSemantic + 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

  1. Descriptions are critical: The model reads tool descriptions to decide what to call. Be explicit about when to use each tool.
  2. Validate parameters: Use JSON Schema constraints (minimum, maximum, enum, pattern) to prevent invalid calls.
  3. Return structured data: Tool results should return structured data (JSON) so the model can reason about them.
  4. 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
阅读完整来源 ↗