Agent Development

Build reliable AI agents that execute multi-step workflows, orchestrate tools, maintain state, and recover from errors using the Claude Agent SDK.

Prerequisites

• Claude API access with appropriate model permissions
• Python 3.10+ or Node.js 18+ environment
• Understanding of the agent's domain and available tools
• Familiarity with async programming patterns

Workflow

Step 1: Define the Agent's Purpose

Establish the agent scope:

1. Mission - single sentence describing what the agent accomplishes
2. Capabilities - list of actions the agent can take
3. Boundaries - what the agent should refuse or escalate
4. Tools - external services and APIs the agent will call
5. State requirements - what information persists across steps
6. Success criteria - how to determine the agent completed its task

Step 2: Design the Tool Set

For each tool the agent will use:

1. Name - descriptive snake_case identifier
2. Description - when and why the agent should use this tool
3. Parameters - input schema with types and validation
4. Return type - what the tool returns on success
5. Error modes - what can go wrong and how to signal it
6. Side effects - does the tool modify external state

Group tools by category:

• Read tools - gather information without side effects
• Write tools - modify external state (require confirmation patterns)
• Compute tools - transform data locally

Step 3: Implement the Agent Loop

Build the core agent execution cycle:

1. Receive user input or task description
2. Plan the approach (system prompt guides strategy)
3. Select and call appropriate tool
4. Process tool result
5. Decide: task complete, need more tools, or error
6. If not complete, return to step 3
7. Return final result to user

Key implementation details:

• Set a maximum iteration limit to prevent infinite loops
• Log each tool call and result for debugging
• Implement checkpoints for long-running tasks
• Add timeout handling for external tool calls

Step 4: Design the System Prompt

Write a system prompt that guides agent behavior:

1. Role definition - what the agent is and its expertise
2. Available tools - summary of each tool and when to use it
3. Decision framework - how to choose between tools
4. Output standards - format and quality requirements
5. Error handling rules - what to do when tools fail
6. Escalation criteria - when to ask the user for help

Step 5: Implement State Management

Design the state that persists across agent turns:

1. Conversation history - messages exchanged with the model
2. Tool call log - record of all tool invocations and results
3. Task state - progress tracking for multi-step workflows
4. Working memory - intermediate results the agent needs later
5. Error state - failed attempts and retry counts

State management patterns:

• Use structured objects, not free-form strings
• Serialize state for persistence across sessions
• Implement state cleanup to prevent context overflow
• Add state validation before each agent step

Step 6: Add Error Recovery

Implement resilient error handling:

1. Retry with backoff - transient failures get 2-3 retries
2. Fallback tools - alternative approaches when primary tool fails
3. Graceful degradation - partial results when full completion is impossible
4. User escalation - ask for help when the agent is stuck
5. State rollback - undo partial changes on failure

Step 7: Test the Agent

Validate agent behavior systematically:

1. Happy path tests - standard inputs produce correct outputs
2. Tool failure tests - agent recovers from individual tool errors
3. Timeout tests - agent handles slow tools gracefully
4. Edge case tests - unusual inputs do not crash the agent
5. Loop detection tests - agent does not repeat the same failed action
6. State tests - agent maintains correct state across many steps

Output Format

The skill produces:

• Agent implementation with tool definitions
• System prompt for agent behavior
• State management module
• Error recovery handlers
• Test suite covering key scenarios
• Configuration for deployment

Examples

Example 1: Research Agent

User: "Build an agent that researches a topic and writes a summary"

Action: Create an agent with tools for web search, page reading, and note taking. The agent plans its research, gathers sources, synthesizes findings, and produces a structured summary.

Example 2: DevOps Agent

User: "Create an agent that monitors and fixes deployment issues"

Action: Create an agent with tools for log querying, metrics checking, service restarting, and notification sending. Implements escalation when automated fixes fail.

Example 3: Data Pipeline Agent

User: "Build an agent that ingests, transforms, and validates data"

Action: Create an agent with tools for file reading, schema validation, data transformation, and database writing. Implements checkpoints and rollback on validation failure.

Best Practices

1. Limit tool breadth - agents with fewer, well-defined tools outperform those with many
2. Make tools idempotent - safe to retry without side effects
3. Log everything - tool calls, decisions, and state changes
4. Set hard limits - maximum iterations, timeout, and token budget
5. Fail fast on invalid input - validate before starting the agent loop
6. Use structured output - parse tool results into typed objects
7. Test the system prompt separately - verify it produces good tool selection
8. Monitor in production - track success rate, latency, and cost per task
9. Version your tools - changing tool schemas requires updating the system prompt
10. Keep state minimal - only persist what the agent genuinely needs

Error Handling