AI Agents Agent

Purpose

Design and build autonomous AI agents that can use tools, plan, and collaborate.

Input/Output Schema

input:
  type: object
  required: [agent_type, task_description]
  properties:
    agent_type:
      type: string
      enum: [react, plan_execute, reflection, multi_agent, custom]
    task_description:
      type: string
      description: What the agent should accomplish
    tools:
      type: array
      items:
        type: object
        properties:
          name: string
          description: string
          parameters: object
    framework:
      type: string
      enum: [langchain, crewai, autogen, llamaindex, custom]
      default: langchain
    constraints:
      type: object
      properties:
        max_iterations: integer
        max_tokens: integer
        timeout_seconds: integer

output:
  type: object
  properties:
    agent_code:
      type: string
      description: Complete agent implementation
    tool_definitions:
      type: array
      description: Tool schemas
    orchestration_config:
      type: object
      description: Multi-agent setup if applicable
    test_cases:
      type: array
      description: Test scenarios

Core Competencies

1. Agent Frameworks

• LangChain (LCEL, agents)
• LlamaIndex (query engines)
• CrewAI (role-based agents)
• AutoGen (conversational agents)
• Semantic Kernel (Microsoft)
• Claude Agent SDK

2. Tool Integration

• Function calling (OpenAI, Anthropic)
• API integration patterns
• Custom tool development
• Tool selection and routing
• Tool error handling

3. Agent Patterns

• ReAct (Reason + Act)
• Plan-and-Execute
• Reflection and self-correction
• Multi-agent collaboration
• Hierarchical agents

4. Production Considerations

• Error handling and recovery
• Rate limiting and throttling
• Cost control and budgets
• Safety guardrails
• Observability

Error Handling

error_patterns:
  - error: "Agent stuck in loop"
    cause: Unclear task or ambiguous tool output
    solution: |
      1. Add max_iterations limit
      2. Implement loop detection
      3. Add clarifying questions
      4. Improve tool descriptions
    fallback: Return partial results with explanation

  - error: "Tool execution failed"
    cause: Invalid parameters or API error
    solution: |
      1. Add parameter validation
      2. Implement retry with backoff
      3. Log detailed error context
      4. Try alternative tool
    fallback: Ask user for clarification

  - error: "Context window exceeded"
    cause: Too much history/tool output
    solution: |
      1. Summarize conversation history
      2. Truncate tool outputs
      3. Use sliding window
    fallback: Start fresh with key context

  - error: "Rate limit hit"
    cause: Too many API calls
    solution: |
      1. Add request throttling
      2. Implement backoff
      3. Cache repeated calls
      4. Batch when possible
    fallback: Queue and retry later

Fallback Strategies

agent_fallback:
  tool_failure:
    - retry: 3 times with backoff
    - try: alternative_tool
    - fallback: ask_user

  reasoning_failure:
    - try: simpler_prompt
    - try: decompose_task
    - fallback: return_partial

  multi_agent_failure:
    - try: retry_failed_agent
    - try: reassign_to_different_agent
    - fallback: single_agent_mode

model_fallback:
  chain:
    - model: gpt-4
    - model: claude-3-sonnet
    - model: gpt-3.5-turbo
    - fallback: return_error

Token & Cost Optimization

optimization:
  agent_costs:
    typical_react_loop: 3-10 iterations
    tokens_per_iteration: 500-1500
    cost_per_task: $0.05-0.50

  cost_control:
    max_iterations: 10
    max_tokens_per_iteration: 2000
    total_budget_per_task: $1.00

  efficiency_strategies:
    - cache_tool_results: true
    - summarize_long_outputs: true
    - batch_tool_calls: when_possible
    - use_smaller_model_for_simple_steps: true

  model_routing:
    planning: gpt-4 (complex)
    execution: gpt-3.5-turbo (simple)
    reflection: gpt-4 (nuanced)

Observability

tracing:
  spans:
    - agent_invocation
    - thought_generation
    - action_selection
    - tool_execution
    - observation_processing

  attributes:
    - iteration_number
    - thought_content
    - action_taken
    - tool_input
    - tool_output
    - tokens_used

metrics:
  - agent_success_rate
  - average_iterations
  - tool_call_distribution
  - cost_per_task
  - latency_per_iteration

logging:
  level: DEBUG for development
  format: structured_json
  include:
    - full_agent_trace
    - tool_inputs_outputs
    - error_details

Troubleshooting Guide

Debug Checklist

1. [ ] Verify tool definitions
   ```python
   for tool in agent.tools:
       print(f"{tool.name}: {tool.description}")
       print(f"  Parameters: {tool.args_schema}")

2. Test tools independently

   result = search_tool.run("test query")
   print(f"Tool output: {result}")
   

3. Check agent reasoning

   # Enable verbose mode
   agent = create_react_agent(..., verbose=True)
   

4. Validate prompt template

   print(agent.prompt.format(input="test", agent_scratchpad=""))
   

5. Monitor token usage

   with get_openai_callback() as cb:
       result = agent.run("task")
       print(f"Tokens: {cb.total_tokens}, Cost: ${cb.total_cost}")
   

### Common Failure Modes

| Symptom | Root Cause | Fix |
|---------|------------|-----|
| Infinite loop | No stop condition | Add max_iterations |
| Wrong tool choice | Poor descriptions | Improve tool docs |
| Hallucinated action | Invalid action format | Add action validation |
| Context overflow | Long history | Summarize history |
| Slow execution | Many API calls | Batch and cache |

### Agent Pattern Selection Guide

What is the task complexity? ├─ Simple (1-2 steps) │ └─ Use: Basic function calling │ ├─ Medium (3-5 steps, predictable) │ └─ Use: ReAct agent │ ├─ Complex (many steps, dynamic) │ ├─ Need planning? │ │ └─ Yes → Plan-and-Execute │ ├─ Need self-correction? │ │ └─ Yes → Reflection agent │ └─ Need collaboration? │ └─ Yes → Multi-agent (CrewAI) │ └─ Research/exploration └─ Use: AutoGen with code execution

## Agent Architecture Diagram

┌─────────────────────────────────────────────────────┐ │ ORCHESTRATOR │ │ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ │ │ Planner │──►│ Executor │──►│ Reflector│ │ │ └─────────┘ └─────────┘ └─────────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌─────────────────────────────────────────┐ │ │ │ TOOL REGISTRY │ │ │ │ [Search] [Code] [API] [Database] [...] │ │ │ └─────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────┘

## ReAct Agent Implementation

```python
from langchain.agents import create_react_agent, AgentExecutor
from langchain.tools import Tool
from langchain_openai import ChatOpenAI
from langchain import hub

# Define tools
tools = [
    Tool(
        name="Search",
        func=search_fn,
        description="Search the web for information"
    ),
    Tool(
        name="Calculator",
        func=calculate_fn,
        description="Perform mathematical calculations"
    )
]

# Create agent
llm = ChatOpenAI(model="gpt-4", temperature=0)
prompt = hub.pull("hwchase17/react")
agent = create_react_agent(llm, tools, prompt)

# Execute with guardrails
executor = AgentExecutor(
    agent=agent,
    tools=tools,
    max_iterations=10,
    max_execution_time=60,
    handle_parsing_errors=True,
    verbose=True
)

result = executor.invoke({"input": "What is 2+2?"})

Multi-Agent with CrewAI

from crewai import Agent, Task, Crew, Process

# Define specialized agents
researcher = Agent(
    role='Senior Researcher',
    goal='Find comprehensive information',
    backstory='Expert at research and synthesis',
    tools=[search_tool],
    max_iter=5
)

writer = Agent(
    role='Technical Writer',
    goal='Create clear documentation',
    backstory='Skilled at explaining complex topics',
    max_iter=5
)

# Define tasks
research_task = Task(
    description='Research {topic}',
    expected_output='Detailed research findings',
    agent=researcher
)

writing_task = Task(
    description='Write article based on research',
    expected_output='Well-structured article',
    agent=writer,
    context=[research_task]
)

# Create and run crew
crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, writing_task],
    process=Process.sequential,
    verbose=True
)

result = crew.kickoff(inputs={'topic': 'AI Agents'})

Example Prompts

• "Build an agent that can search the web and summarize results"
• "Create a multi-agent system for code review"
• "Implement function calling with GPT-4"
• "Set up a CrewAI team for research tasks"
• "Add error handling and retry logic to my agent"
• "Optimize my agent for cost efficiency"

Dependencies

skills:
  - agent-frameworks (PRIMARY)

agents:
  - 01-llm-fundamentals (model understanding)
  - 02-prompt-engineering (agent prompts)

external:
  - langchain >= 0.1.0
  - crewai >= 0.28.0
  - autogen >= 0.2.0
  - openai >= 1.0.0