---

name: ai-agents description: Building AI agents - tool use, planning strategies (ReAct, Plan-and-Execute), memory systems, agent evaluation. Use when building autonomous AI systems, tool-augmented apps, or multi-step workflows.

AI Agents

Building AI agents with tools and planning.

Agent Architecture

Copy┌─────────────────────────────────────┐
│            AI AGENT                  │
├─────────────────────────────────────┤
│  ┌──────────┐                       │
│  │  BRAIN   │  (Foundation Model)   │
│  │ Planning │                       │
│  │ Reasoning│                       │
│  └────┬─────┘                       │
│       │                             │
│   ┌───┴───┐                         │
│   ↓       ↓                         │
│ ┌─────┐ ┌──────┐                    │
│ │TOOLS│ │MEMORY│                    │
│ └─────┘ └──────┘                    │
└─────────────────────────────────────┘

Tool Definition

Copytools = [{
    "type": "function",
    "function": {
        "name": "search_database",
        "description": "Search products by query",
        "parameters": {
            "type": "object",
            "properties": {
                "query": {"type": "string"},
                "category": {"type": "string", "enum": ["electronics", "clothing"]},
                "max_price": {"type": "number"}
            },
            "required": ["query"]
        }
    }
}]

Planning Strategies

ReAct (Reasoning + Acting)

CopyREACT_PROMPT = """Tools: {tools}

Format:
Thought: [reasoning]
Action: [tool_name]
Action Input: [JSON]
Observation: [result]
... repeat ...
Final Answer: [answer]

Question: {question}
Thought:"""

def react_agent(question, tools, max_steps=10):
    prompt = REACT_PROMPT.format(...)

    for _ in range(max_steps):
        response = llm.generate(prompt)

        if "Final Answer:" in response:
            return extract_answer(response)

        action, input = parse_action(response)
        observation = execute(tools[action], input)
        prompt += f"\nObservation: {observation}\nThought:"

Plan-and-Execute

Copydef plan_and_execute(task, tools):
    # Step 1: Create plan
    plan = llm.generate(f"Create step-by-step plan for: {task}")
    steps = parse_plan(plan)

    # Step 2: Execute each step
    results = []
    for step in steps:
        result = execute_step(step, tools)
        results.append(result)

    # Step 3: Synthesize
    return synthesize(task, results)

Reflexion (Self-Reflection)

Copydef reflexion_agent(task, max_attempts=3):
    memory = []

    for attempt in range(max_attempts):
        solution = generate(task, memory)
        success, feedback = evaluate(solution)

        if success:
            return solution

        reflection = reflect(task, solution, feedback)
        memory.append({"solution": solution, "reflection": reflection})

Memory Systems

Copyclass AgentMemory:
    def __init__(self):
        self.short_term = []        # Recent turns
        self.long_term = VectorDB() # Persistent

    def add(self, message):
        self.short_term.append(message)
        if len(self.short_term) > 20:
            self.consolidate()

    def consolidate(self):
        summary = summarize(self.short_term[:10])
        self.long_term.add(summary)
        self.short_term = self.short_term[10:]

    def retrieve(self, query, k=5):
        return {
            "recent": self.short_term[-5:],
            "relevant": self.long_term.search(query, k),
        }

Agent Evaluation

Copydef evaluate_agent(agent, test_cases):
    return {
        "task_success": mean([agent.run(c["task"]) == c["expected"] for c in test_cases]),
        "avg_steps": mean([agent.step_count for _ in test_cases]),
        "avg_latency": mean([measure_time(agent.run, c["task"]) for c in test_cases]),
    }

Best Practices

1. Start with simple tools, add complexity gradually
2. Add reflection for complex tasks
3. Limit max steps to prevent infinite loops
4. Log all agent actions for debugging
5. Use evaluation to measure progress