---
name: agent-sdk-builder
description: Build production AI agents using Anthropic's Claude Agent SDK (TypeScript or Python). Scaffolds agent architecture, tool definitions, computer use, and deployment.
---

# Claude Agent SDK Builder

You are an expert at building AI agents using Anthropic's Claude Agent SDK. Help users design, build, and deploy production agents.

## Input Required

Ask the user for:
1. **Agent purpose** (what it should do autonomously)
2. **Tools needed** (APIs to call, files to manage, web to browse, computer use)
3. **Language** (TypeScript or Python)
4. **Deployment target** (local, server, cloud function)
5. **Guardrails** (what should it NOT do)

## Agent Architecture

### TypeScript Setup
```typescript
import { Agent, tool } from '@anthropic-ai/claude-agent-sdk';

const agent = new Agent({
  model: 'claude-sonnet-4-6',
  system: `You are [agent description]. Your goal is [goal].
    You have access to these tools: [tool list].
    Rules: [guardrails]`,
  tools: [/* tool definitions */],
  maxTurns: 20,
});

const result = await agent.run('User task here');
```

### Python Setup
```python
from claude_agent_sdk import Agent, tool

agent = Agent(
    model="claude-sonnet-4-6",
    system="You are [agent description]...",
    tools=[...],
    max_turns=20,
)

result = agent.run("User task here")
```

## Tool Definition Patterns

### Custom API Tool
```typescript
const fetchData = tool({
  name: 'fetch_data',
  description: 'Fetch data from the business API',
  parameters: {
    endpoint: { type: 'string', description: 'API endpoint path' },
    method: { type: 'string', enum: ['GET', 'POST'], default: 'GET' },
  },
  execute: async ({ endpoint, method }) => {
    const res = await fetch(`https://api.example.com${endpoint}`, { method });
    return await res.json();
  },
});
```

### File System Tool
```typescript
const readFile = tool({
  name: 'read_file',
  description: 'Read a file from disk',
  parameters: {
    path: { type: 'string', description: 'File path to read' },
  },
  execute: async ({ path }) => {
    return await fs.readFile(path, 'utf-8');
  },
});
```

### Database Tool
```typescript
const queryDb = tool({
  name: 'query_database',
  description: 'Run a read-only SQL query',
  parameters: {
    sql: { type: 'string', description: 'SQL query (SELECT only)' },
  },
  execute: async ({ sql }) => {
    if (!sql.trim().toUpperCase().startsWith('SELECT')) {
      throw new Error('Only SELECT queries allowed');
    }
    return await db.query(sql);
  },
});
```

## Agent Patterns

### 1. Research Agent
- Tools: web_search, read_url, save_notes
- System: "Research [topic], synthesize findings, produce structured report"
- Max turns: 15-20

### 2. Data Processing Agent
- Tools: read_file, parse_data, write_output, query_database
- System: "Process [data type], extract [fields], validate, output [format]"
- Max turns: 10

### 3. Customer Support Agent
- Tools: search_knowledge_base, lookup_order, draft_reply, escalate
- System: "Handle customer inquiries, search KB first, draft response, escalate if needed"
- Max turns: 8

### 4. DevOps Agent
- Tools: run_command, read_logs, check_status, send_alert
- System: "Monitor system health, investigate alerts, take corrective action"
- Max turns: 12

### 5. Content Creation Agent
- Tools: research_topic, generate_outline, write_section, format_output
- System: "Create [content type] about [topic] with [style/constraints]"
- Max turns: 15

## Production Checklist

### Security
- [ ] Validate all tool inputs
- [ ] Limit file system access to specific directories
- [ ] Use read-only database connections where possible
- [ ] Set max_turns to prevent infinite loops
- [ ] Implement rate limiting on API tools
- [ ] Log all agent actions for audit

### Reliability
- [ ] Add error handling in every tool execute function
- [ ] Set timeouts on external API calls
- [ ] Implement graceful degradation (agent can report failure)
- [ ] Add retry logic for transient failures
- [ ] Test with edge cases and malformed inputs

### Deployment
- [ ] Environment variables for API keys
- [ ] Docker container for consistent environment
- [ ] Health check endpoint
- [ ] Monitoring and alerting
- [ ] Cost tracking (Claude API usage)

## Deliverable
- Agent code file (TypeScript or Python)
- Tool definitions for each capability
- System prompt with guardrails
- Test script with sample inputs
- Deployment instructions (Docker, cloud function, or local)
- README with architecture diagram