{"id":46076100,"url":"https://github.com/ry-ops/building-your-first-claude-agent","last_synced_at":"2026-03-01T14:35:16.017Z","repository":{"id":336649515,"uuid":"1143333909","full_name":"ry-ops/building-your-first-claude-agent","owner":"ry-ops","description":"Learn to build intelligent agents with Claude that automate your workflow","archived":false,"fork":false,"pushed_at":"2026-02-03T01:10:27.000Z","size":33,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-02-06T00:10:01.314Z","etag":null,"topics":["agents","ai","anthropic","claude","tutorial","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ry-ops.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-27T13:03:57.000Z","updated_at":"2026-02-03T15:47:22.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/ry-ops/building-your-first-claude-agent","commit_stats":null,"previous_names":["ry-ops/building-your-first-claude-agent"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/ry-ops/building-your-first-claude-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Fbuilding-your-first-claude-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Fbuilding-your-first-claude-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Fbuilding-your-first-claude-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Fbuilding-your-first-claude-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ry-ops","download_url":"https://codeload.github.com/ry-ops/building-your-first-claude-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ry-ops%2Fbuilding-your-first-claude-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29971002,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-01T14:11:48.712Z","status":"ssl_error","status_checked_at":"2026-03-01T14:11:48.352Z","response_time":124,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agents","ai","anthropic","claude","tutorial","typescript"],"created_at":"2026-03-01T14:35:14.851Z","updated_at":"2026-03-01T14:35:15.997Z","avatar_url":"https://github.com/ry-ops.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Building Your First Claude Agent\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"hero.svg\" alt=\"Building Your First Claude Agent\" width=\"100%\"\u003e\n\u003c/p\u003e\n\nA comprehensive, production-ready guide to building AI agents with Claude and the Anthropic SDK in TypeScript.\n\n## Overview\n\nThis repository provides a complete framework for building autonomous AI agents powered by Claude. It includes:\n\n- Production-ready agent implementation with error handling and retries\n- Example tools for common operations (calculator, file I/O, web search)\n- Multi-step workflow examples (data analysis, code review)\n- Comprehensive documentation and API reference\n- TypeScript throughout for type safety\n\n## Quick Start\n\n### Prerequisites\n\n- Node.js 18 or higher\n- An Anthropic API key ([get one here](https://console.anthropic.com))\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/ry-ops/building-your-first-claude-agent.git\ncd building-your-first-claude-agent\n\n# Install dependencies\nnpm install\n\n# Set up environment variables\ncp .env.example .env\n# Edit .env and add your ANTHROPIC_API_KEY\n```\n\n### Your First Agent\n\nCreate a simple agent in just a few lines:\n\n```typescript\nimport { ClaudeAgent } from './src/agent';\nimport { calculatorTool } from './src/tools';\n\nconst agent = new ClaudeAgent({\n  apiKey: process.env.ANTHROPIC_API_KEY,\n});\n\nagent.registerTool(calculatorTool);\n\nconst response = await agent.execute(\n  'What is 157 multiplied by 23?'\n);\n\nconsole.log(response.content);\n// \"The product of 157 and 23 is 3,611.\"\n```\n\n### Run Examples\n\n```bash\n# Simple agent with tools\nnpm run example:simple\n\n# Multi-step workflow\nnpm run example:workflow\n```\n\n## Core Concepts\n\n### What is an AI Agent?\n\nAn AI agent is an autonomous system that can:\n\n1. **Understand** complex instructions\n2. **Plan** sequences of actions\n3. **Execute** actions using tools\n4. **Adapt** based on results\n5. **Respond** with meaningful output\n\nUnlike chatbots that just respond to messages, agents can use external tools, make decisions, and accomplish complex tasks autonomously.\n\n### Agent Architecture\n\n```\n┌─────────────────────────────────────────┐\n│           User Instruction              │\n└──────────────┬──────────────────────────┘\n               │\n               ▼\n┌─────────────────────────────────────────┐\n│          Claude Agent                   │\n│  - Conversation History                 │\n│  - Tool Registry                        │\n│  - Retry Logic                          │\n└──────────────┬──────────────────────────┘\n               │\n               ▼\n┌─────────────────────────────────────────┐\n│         Anthropic API                   │\n│  (Claude Model + Tool Use)              │\n└──────────────┬──────────────────────────┘\n               │\n               ▼\n        ┌──────┴──────┐\n        │             │\n        ▼             ▼\n  ┌──────────┐  ┌──────────┐\n  │  Tools   │  │ Response │\n  └──────────┘  └──────────┘\n        │\n        └─────────────┐\n                      │\n                      ▼\n              ┌──────────────┐\n              │ Tool Results │\n              └──────────────┘\n                      │\n                      └─────► (back to Claude)\n```\n\n### The Agent Loop\n\n1. User sends a message\n2. Agent forwards to Claude with available tools\n3. Claude responds with either:\n   - A tool use request → Execute tool → Return to step 2\n   - A text response → Return to user\n\nThis loop continues until Claude has the information needed to respond.\n\n### Tools\n\nTools are functions that agents can call:\n\n- **File operations**: Read, write, list files\n- **Calculations**: Math operations\n- **Web interactions**: Search, API calls\n- **Code execution**: Run scripts, commands\n- **Data processing**: Transform, analyze data\n\nEach tool has:\n- **Name**: Unique identifier\n- **Description**: When and how to use it\n- **Input Schema**: Expected parameters\n- **Execute Function**: Implementation\n\n## Project Structure\n\n```\nbuilding-your-first-claude-agent/\n├── src/\n│   ├── agent.ts              # Core agent implementation\n│   ├── tools/                # Tool implementations\n│   │   ├── calculator.ts     # Math operations\n│   │   ├── file-operations.ts # File I/O\n│   │   ├── web-search.ts     # Web search (simulated)\n│   │   └── index.ts\n│   └── workflows/            # Example workflows\n│       ├── data-analysis.ts  # Data analysis workflow\n│       ├── code-review.ts    # Code review workflow\n│       └── index.ts\n├── examples/\n│   ├── simple-agent.ts       # Basic agent usage\n│   └── multi-step-workflow.ts # Complex workflow\n├── documentation/\n│   ├── AGENT-CONCEPTS.md     # Core concepts\n│   ├── WORKFLOW-DESIGN.md    # Workflow patterns\n│   └── API-REFERENCE.md      # Complete API docs\n├── package.json\n├── tsconfig.json\n├── .env.example\n├── .gitignore\n├── LICENSE\n└── README.md\n```\n\n## Features\n\n### Production-Ready Agent\n\n- **Automatic retries** with exponential backoff\n- **Error handling** for API failures and tool errors\n- **Conversation history** management\n- **Token usage** tracking\n- **Type safety** with TypeScript\n\n### Example Tools\n\n1. **Calculator**: Basic math operations\n2. **File Operations**: Read, write, list files\n3. **Web Search**: Simulated search (integrate real APIs)\n\n### Example Workflows\n\n1. **Data Analysis**: Read data, analyze, generate reports\n2. **Code Review**: Review code, identify issues, suggest improvements\n\n### Comprehensive Documentation\n\n- **Agent Concepts**: Understanding agent architecture\n- **Workflow Design**: Building multi-step workflows\n- **API Reference**: Complete API documentation\n\n## Usage Examples\n\n### Simple Calculator\n\n```typescript\nimport { ClaudeAgent } from './src/agent';\nimport { calculatorTool } from './src/tools';\n\nconst agent = new ClaudeAgent({\n  apiKey: process.env.ANTHROPIC_API_KEY,\n});\n\nagent.registerTool(calculatorTool);\n\nconst response = await agent.execute(\n  'Calculate the sum of 456 and 789, then multiply by 2'\n);\n```\n\n### File Operations\n\n```typescript\nimport { ClaudeAgent } from './src/agent';\nimport { readFileTool, writeFileTool } from './src/tools';\n\nconst agent = new ClaudeAgent({\n  apiKey: process.env.ANTHROPIC_API_KEY,\n});\n\nagent.registerTools([readFileTool, writeFileTool]);\n\nawait agent.execute(`\n  Read the data from ./input.json,\n  process it, and write the results to ./output.json\n`);\n```\n\n### Data Analysis Workflow\n\n```typescript\nimport { DataAnalysisWorkflow } from './src/workflows';\n\nconst workflow = new DataAnalysisWorkflow({\n  apiKey: process.env.ANTHROPIC_API_KEY,\n  inputFilePath: './data/sales.json',\n  outputFilePath: './data/report.md',\n});\n\nconst result = await workflow.execute();\nconsole.log(result.analysis);\n```\n\n### Code Review Workflow\n\n```typescript\nimport { CodeReviewWorkflow } from './src/workflows';\n\nconst workflow = new CodeReviewWorkflow({\n  apiKey: process.env.ANTHROPIC_API_KEY,\n  targetPath: './src',\n  outputPath: './review.md',\n  reviewCriteria: [\n    'Code quality and readability',\n    'Security vulnerabilities',\n    'Performance issues',\n  ],\n});\n\nconst result = await workflow.execute();\nconsole.log(`Found ${result.issues.length} issues`);\n```\n\n### Custom Tools\n\nCreate your own tools easily:\n\n```typescript\nimport { AgentTool } from './src/agent';\n\nconst timestampTool: AgentTool = {\n  name: 'get_timestamp',\n  description: 'Returns the current timestamp',\n  input_schema: {\n    type: 'object',\n    properties: {\n      format: {\n        type: 'string',\n        enum: ['iso', 'unix'],\n        description: 'Timestamp format',\n      },\n    },\n    required: ['format'],\n  },\n  execute: async (input) =\u003e {\n    if (input.format === 'iso') {\n      return { timestamp: new Date().toISOString() };\n    } else {\n      return { timestamp: Date.now() };\n    }\n  },\n};\n\nagent.registerTool(timestampTool);\n```\n\n## Advanced Features\n\n### System Prompts\n\nGuide agent behavior with system prompts:\n\n```typescript\nconst response = await agent.execute(\n  'Review this code for security issues',\n  `You are a security expert specializing in web application security.\n   Focus on common vulnerabilities like SQL injection, XSS, and CSRF.\n   Provide specific, actionable recommendations.`\n);\n```\n\n### Conversation History\n\nMaintain context across multiple turns:\n\n```typescript\n// First turn\nawait agent.execute('Calculate 50 + 25');\n\n// Second turn - references previous calculation\nconst response = await agent.execute(\n  'Now multiply that result by 3'\n);\n\n// Clear history when starting new task\nagent.clearHistory();\n```\n\n### Error Handling\n\nRobust error handling with retries:\n\n```typescript\nconst agent = new ClaudeAgent({\n  apiKey: process.env.ANTHROPIC_API_KEY,\n  maxRetries: 5,           // Retry up to 5 times\n  retryDelayMs: 2000,      // Start with 2s delay\n});\n\ntry {\n  const response = await agent.execute('Your task');\n} catch (error) {\n  if (error.status === 429) {\n    console.error('Rate limited');\n  } else {\n    console.error('Failed:', error.message);\n  }\n}\n```\n\n## Documentation\n\n- **[Agent Concepts](./documentation/AGENT-CONCEPTS.md)**: Learn the fundamentals of agent architecture\n- **[Workflow Design](./documentation/WORKFLOW-DESIGN.md)**: Design complex multi-step workflows\n- **[API Reference](./documentation/API-REFERENCE.md)**: Complete API documentation\n\n## Best Practices\n\n### 1. Clear Tool Descriptions\n\n```typescript\n// Good: Clear and specific\ndescription: 'Reads the contents of a file. Use when you need to access file data.'\n\n// Bad: Vague\ndescription: 'File stuff'\n```\n\n### 2. Validate Tool Inputs\n\n```typescript\nexecute: async (input) =\u003e {\n  if (!input.file_path) {\n    throw new Error('file_path is required');\n  }\n  if (!fs.existsSync(input.file_path)) {\n    throw new Error('File not found');\n  }\n  // ... proceed with execution\n}\n```\n\n### 3. Use System Prompts\n\n```typescript\nconst systemPrompt = `\nYou are a professional data analyst.\nAlways use tools when available.\nFormat reports with clear sections.\n`;\n\nawait agent.execute(userMessage, systemPrompt);\n```\n\n### 4. Monitor Token Usage\n\n```typescript\nconst response = await agent.execute(message);\nconsole.log(`Tokens: ${response.usage?.inputTokens} in, ${response.usage?.outputTokens} out`);\n```\n\n### 5. Handle Errors Gracefully\n\n```typescript\ntry {\n  await workflow.execute();\n} catch (error) {\n  console.error('Workflow failed:', error);\n  // Implement recovery logic\n}\n```\n\n## Environment Variables\n\nCopy `.env.example` to `.env` and configure:\n\n```bash\n# Required\nANTHROPIC_API_KEY=your_api_key_here\n\n# Optional\nMODEL_NAME=claude-sonnet-4-5-20250929\nMAX_TOKENS=4096\nTEMPERATURE=0.7\nMAX_RETRIES=3\nRETRY_DELAY_MS=1000\n```\n\n## Building and Running\n\n```bash\n# Install dependencies\nnpm install\n\n# Build TypeScript\nnpm run build\n\n# Run examples\nnpm run example:simple\nnpm run example:workflow\n\n# Development mode\nnpm run dev\n```\n\n## Contributing\n\nContributions are welcome! Please feel free to submit issues and pull requests.\n\n## License\n\nMIT License - see [LICENSE](./LICENSE) for details.\n\nCopyright (c) 2026 ry-ops\n\n## Resources\n\n- [Anthropic API Documentation](https://docs.anthropic.com)\n- [Claude Tool Use Guide](https://docs.anthropic.com/claude/docs/tool-use)\n- [TypeScript SDK](https://github.com/anthropics/anthropic-sdk-typescript)\n- [Prompt Engineering Guide](https://docs.anthropic.com/claude/docs/prompt-engineering)\n\n## Support\n\nFor issues and questions:\n\n- Open an issue on GitHub\n- Check the [documentation](./documentation/)\n- Review the [examples](./examples/)\n\n## Roadmap\n\nFuture enhancements:\n\n- [ ] More example tools (database, email, etc.)\n- [ ] Streaming responses\n- [ ] Multi-agent systems\n- [ ] Advanced workflow patterns\n- [ ] Testing framework\n- [ ] Performance benchmarks\n\n---\n\nBuilt with Claude Sonnet 4.5 by ry-ops\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fry-ops%2Fbuilding-your-first-claude-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fry-ops%2Fbuilding-your-first-claude-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fry-ops%2Fbuilding-your-first-claude-agent/lists"}