Using AI Agents

Learn how to effectively use AI agents in your Claude Code workflow to boost productivity and code quality.

Agents are specialized Claude Code configurations that bring domain expertise to specific tasks.

Quick Reference

# Invoke an agent
/agent backend-builder "Create a REST API for sports leagues"
 
# List available agents
claude agents list
 
# Get agent help
/agent backend-builder --help
 
# Use in conversation
"Can you use the backend-builder agent to create an API?"

Agent Invocation

Slash Command (Recommended)

/agent <agent-name> "<task-description>" [options]

Examples:

# Backend development
/agent backend-builder "Create a FastAPI sports API with PostgreSQL"
 
# Frontend design
/agent frontend-designer "Design a dashboard for league analytics" --framework nextjs
 
# AI orchestration
/agent ai-orchestrator "Build a document pipeline" --all

Natural Language

Simply mention the agent in conversation:

User: "I need a REST API for managing sports leagues with teams and players"
Claude: "I'll use the backend-builder agent to create that for you."

Claude automatically detects which agent to use based on context.

Agent Workflow

Agent Selection

Claude Code selects the appropriate agent based on:

Task keywords - "API", "design", "orchestration"
Context - Current files, project type
Explicit mention - You specify the agent

Task Analysis

The agent analyzes your request:

Extracts requirements
Identifies constraints
Determines output format
Plans implementation steps

Execution

Agent executes with:

Domain expertise applied
Best practices enforced
Quality standards met
Comprehensive output generated

Review & Iterate

Review agent output:

Check generated code/specs
Test functionality
Request refinements if needed
Provide feedback for improvement

Agent Options

Common Options

# Specify framework/runtime
--runtime python
--framework fastapi
 
# Choose output type
--output standalone      # Complete project
--output mcp-server     # MCP server
--output library        # Reusable library
 
# Database selection
--database postgres
--database mongo
 
# Deployment target
--deployment cloud-run
--deployment docker

Builder-Specific Options

/agent backend-builder "Create API" \
  --runtime python \
  --framework fastapi \
  --database postgres \
  --deployment cloud-run \
  --with-tests \
  --with-docs

Designer-Specific Options

/agent frontend-designer "Design dashboard" \
  --framework nextjs \
  --design-system shadcn \
  --approach dashboard-first \
  --wcag-level AA

Orchestrator-Specific Options

/agent ai-orchestrator "Build pipeline" \
  --all                    # All frameworks
  --framework langgraph    # Single framework
  --output comparative     # With comparison

Best Practices

1. Be Specific

# ❌ Too vague
/agent backend-builder "Create an API"
 
# ✅ Specific and clear
/agent backend-builder "Create a REST API for sports leagues with:
- CRUD for leagues, teams, players
- JWT authentication
- PostgreSQL database
- Real-time updates via WebSocket
- Deploy to Google Cloud Run"

2. Provide Context

Include relevant information:

Tech stack preferences
Existing systems to integrate with
Performance requirements
Security constraints
Timeline or milestones

3. Iterate Incrementally

# Start simple
/agent backend-builder "Basic CRUD API for leagues"
 
# Add features incrementally
/agent backend-builder "Add authentication to the league API"
 
# Enhance further
/agent backend-builder "Add WebSocket support for real-time updates"

4. Review and Test

Always:

✅ Review generated code
✅ Run tests
✅ Check security
✅ Validate performance
✅ Test deployment

5. Leverage Agent Strengths

Each agent excels at different tasks:

Agent	Best For	Avoid For
Backend Builder	APIs, services, MCP servers	UI design, frontend code
Frontend Designer	UI specs, design systems	Backend implementation
AI Orchestrator	Multi-agent workflows	Simple single-agent tasks

Common Workflows

Full-Stack Development

# 1. Design the UI
/agent frontend-designer "Design sports dashboard"
 
# 2. Build the backend
/agent backend-builder "Create sports API based on frontend design"
 
# 3. Integrate
# Use both outputs to build integrated application

API Development

# 1. Build API
/agent backend-builder "Create sports league REST API"
 
# 2. Add features
/agent backend-builder "Add authentication and rate limiting"
 
# 3. Deploy
/agent backend-builder "Generate Cloud Run deployment config"

AI Workflow Development

# 1. Compare frameworks
/agent ai-orchestrator "Document processing pipeline" --all
 
# 2. Review comparison
# Analyze comparison.md
 
# 3. Implement chosen framework
/agent ai-orchestrator "Document processing pipeline" --framework langgraph

Troubleshooting

Agent Not Found

# List available agents
claude agents list
 
# Search for agents
claude agents search "backend"
 
# Check agent name
/agent backend-builder  # Correct
/agent backend-agent    # Wrong

Wrong Agent Selected

Be explicit:

# Instead of
"Build an API"  # Might select wrong agent
 
# Use
/agent backend-builder "Build an API"  # Explicit selection

Output Not as Expected

Provide more details:

# Instead of
/agent backend-builder "API for leagues"
 
# Provide details
/agent backend-builder "FastAPI REST API for:
- League CRUD (name, sport, country, year)
- Team relationships
- Player management
- PostgreSQL with SQLAlchemy
- JWT authentication
- Pytest test suite
- Docker deployment"

Agent Asks Too Many Questions

Provide upfront information:

/agent backend-builder "Create API" \
  --runtime python \
  --framework fastapi \
  --database postgres \
  --deployment docker \
  --with-tests \
  --with-auth

Advanced Usage

Agent Chaining

Use multiple agents in sequence:

# 1. Design
/agent frontend-designer "Sports dashboard"
 
# 2. Build backend for design
/agent backend-builder "API to support the dashboard design"
 
# 3. Optimize
/agent performance-optimizer "Optimize the API for 1000+ requests/sec"
 
# 4. Secure
/agent security-auditor "Security review of the complete system"

Custom Agent Configuration

Create project-specific agent settings:

# .claude/agent-config.yaml
backend-builder:
  defaults:
    runtime: python
    framework: fastapi
    database: postgres
    deployment: cloud-run
 
frontend-designer:
  defaults:
    framework: nextjs
    design-system: shadcn
    approach: dashboard-first

Agent Templates

Save common agent invocations:

# .claude/agent-templates.yaml
sports-api:
  agent: backend-builder
  prompt: |
    Create a production-ready sports API with:
    - League, Team, Player, Game entities
    - PostgreSQL database
    - JWT authentication
    - WebSocket for live updates
    - Comprehensive tests
    - Cloud Run deployment
 
dashboard-design:
  agent: frontend-designer
  prompt: |
    Design a sports analytics dashboard with:
    - Key metrics cards
    - Interactive charts
    - Data tables with filtering
    - Real-time updates
    - Mobile responsive

Use templates:

/agent-template sports-api
/agent-template dashboard-design

Integration with Development Workflow

Git Integration

# 1. Create feature branch
git checkout -b feature/sports-api
 
# 2. Use agent
/agent backend-builder "Sports API implementation"
 
# 3. Review changes
git diff
 
# 4. Commit
git add .
git commit -m "Add sports API implementation
 
Generated using backend-builder agent with:
- FastAPI framework
- PostgreSQL database
- JWT authentication
- Comprehensive tests"
 
# 5. Push and create PR
git push origin feature/sports-api
gh pr create

CI/CD Integration

Agents generate CI/CD configurations:

/agent backend-builder "Create API with GitHub Actions CI/CD"

Generated:

.github/workflows/test.yml - Test workflow
.github/workflows/deploy.yml - Deployment workflow
Dockerfile - Container definition
docker-compose.yml - Local testing

Documentation Integration

Agents generate comprehensive docs:

/agent backend-builder "Sports API with OpenAPI docs"