---
name: majiayu000/claude-agent-ts-sdk
source: https://app.decimal.ai/s/majiayu000-claude-agent-ts-sdk@1/SKILL.md
source_sha256: 05120711991d
---

# Claude Agent TypeScript SDK

Build production-ready Claude agents using TypeScript and the `@anthropic-ai/claude-agent-sdk`. This skill provides battle-tested patterns for creating modular, composable agent tools.

## Quick Start

```typescript
import { query, createSdkMcpServer, tool } from '@anthropic-ai/claude-agent-sdk';
import { z } from 'zod';

// 1. Define tools
const greetTool = tool(
  'greet',
  'Greet a user by name',
  z.object({
    name: z.string().describe('User name'),
  }).shape,
  async ({ name }) => ({
    content: [{ type: 'text', text: `Hello, ${name}!` }],
  })
);

// 2. Create MCP server
const server = createSdkMcpServer({
  name: 'my-agent',
  version: '1.0.0',
  tools: [greetTool],
});

// 3. Query with streaming
const messages = query({
  prompt: 'Greet Alice',
  options: {
    systemPrompt: 'You are a helpful agent.',
    permissionMode: 'bypassPermissions',
    mcpServers: { 'my-agent': server },
  },
});

// 4. Process stream
for await (const event of messages) {
  if (event.type === 'assistant') {
    for (const content of event.message.content) {
      if (content.type === 'text') {
        console.log(content.text);
      }
    }
  }
}
```

## When to Use This Skill

Use when:
- **Implementing agents**: Building CLI tools, web servers, or plugins
- **Creating tools**: Defining agent capabilities and integrations
- **Handling streams**: Processing agent responses in real-time
- **Debugging**: Troubleshooting agent implementations
- **Migrating**: Converting from MCP servers to tool wrapping approach

## Core Concepts

### 1. Tools

Tools are the building blocks of agent capabilities. Use the `tool()` function to create them:

```typescript
import { tool } from '@anthropic-ai/claude-agent-sdk';
import { z } from 'zod';

const myTool = tool(
  'tool_name',           // Name (lowercase, underscores)
  'What it does',        // Clear description
  z.object({            // Zod schema for validation
    param: z.string().describe('Parameter description'),
  }).shape,
  async (params) => {   // Implementation
    return {
      content: [{ type: 'text', text: 'Result' }],
    };
  }
);
```

**Key Points:**
- Use Zod for schema validation
- Descriptions guide Claude's tool selection
- Return format: `{ content: [{ type: 'text', text: string }] }`
- **For advanced patterns, see references/tools.md**

### 2. MCP Servers

Wrap tools in MCP servers for query execution:

```typescript
import { createSdkMcpServer } from '@anthropic-ai/claude-agent-sdk';

const server = createSdkMcpServer({
  name: 'server-name',
  version: '1.0.0',
  tools: [tool1, tool2],
});
```

**Important:** Create servers at query time, not module level (enables dynamic tool selection).

### 3. Query and Streaming

Execute agent queries with real-time streaming:

```typescript
import { query } from '@anthropic-ai/claude-agent-sdk';

const messages = query({
  prompt: 'User request here',
  options: {
    systemPrompt: 'Agent role and instructions',
    permissionMode: 'bypassPermissions',  // For standalone servers
    mcpServers: {
      'server-name': server,
    },
  },
});

for await (const event of messages) {
  // Process events: 'assistant', 'user', 'error'
}
```

**For streaming patterns and event handling, see references/streaming.md**

### 4. System Prompts

System prompts define agent behavior (100-170+ lines recommended):

```typescript
const SYSTEM_PROMPT = `You are a specialized agent that...

## Available Tools
[Detailed tool descriptions]

## Workflow
[Step-by-step instructions]

## Output Format
[Expected response structure]
`;
```

**For system prompt best practices, see references/system-prompts.md**

## Architecture Patterns

Choose the pattern that fits your use case:

### Pattern 1: CLI/Specialized Agent
**Best for:** Command-line tools, batch processing

```typescript
export async function runAgent(userPrompt: string) {
  const server = createSdkMcpServer({ name: 'cli-agent', version: '1.0.0', tools });
  const messages = query({ prompt: userPrompt, options: { systemPrompt, permissionMode: 'bypassPermissions', mcpServers: { 'cli-agent': server } } });

  for await (const event of messages) {
    if (event.type === 'assistant') {
      for (const content of event.message.content) {
        if (content.type === 'text') process.stdout.write(content.text);
      }
    }
  }
}
```

### Pattern 2: Web Server Agent
**Best for:** Web applications, APIs, real-time UIs

```typescript
app.post('/agent/stream', async (req, res) => {
  res.setHeader('Content-Type', 'text/event-stream');
  const server = createSdkMcpServer({ name: 'web-agent', version: '1.0.0', tools });
  const messages = query({ prompt: req.body.prompt, options: { systemPrompt, mcpServers: { 'web-agent': server } } });

  for await (const event of messages) {
    res.write(`data: ${JSON.stringify(event)}\n\n`);
  }
  res.end();
});
```

### Pattern 3: Plugin/Framework
**Best for:** Extensible systems, plugin architectures

```typescript
export class AgentEngine {
  async stream(prompt: string) {
    const tools = this.plugin.getTools();
    const server = createSdkMcpServer({ name: this.plugin.name, version: '1.0.0', tools });
    const messages = query({ prompt, options: { systemPrompt: this.plugin.systemPrompt, permissionMode: 'bypassPermissions', mcpServers: { [this.plugin.name]: server } } });

    for await (const event of messages) {
      await this.plugin.handleEvent(event);
    }
  }
}
```

**For complete architecture patterns including monorepo setup, see references/patterns.md**

## Project Setup

### Minimal package.json

```json
{
  "name": "my-agent",
  "type": "module",
  "dependencies": {
    "@anthropic-ai/claude-agent-sdk": "^0.1.14",
    "zod": "^3.23.8"
  },
  "devDependencies": {
    "typescript": "^5.3.3",
    "tsx": "^4.7.0"
  }
}
```

### Directory Structure

```
my-agent/
├── src/
│   ├── index.ts              # Entry point
│   ├── agent.ts              # Agent implementation
│   ├── tools/                # Tool definitions
│   └── prompts/              # System prompts
├── package.json
└── tsconfig.json
```

**For complete project setup including TypeScript config, see references/project-setup.md**

## Common Workflows

### Creating a File Management Agent

1. **Define tools:**
```typescript
const readFile = tool('read_file', 'Read file contents',
  z.object({ path: z.string() }).shape,
  async ({ path }) => ({ content: [{ type: 'text', text: await fs.readFile(path, 'utf-8') }] })
);

const writeFile = tool('write_file', 'Write to file',
  z.object({ path: z.string(), content: z.string() }).shape,
  async ({ path, content }) => { await fs.writeFile(path, content); return { content: [{ type: 'text', text: 'Done' }] }; }
);
```

2. **Create system prompt:**
```typescript
const SYSTEM_PROMPT = `You are a file management agent.

When user asks to edit a file:
1. read_file to see current contents
2. Propose changes
3. write_file to save changes`;
```

3. **Set up agent:**
```typescript
const server = createSdkMcpServer({ name: 'files', version: '1.0.0', tools: [readFile, writeFile] });
const messages = query({ prompt: userRequest, options: { systemPrompt: SYSTEM_PROMPT, permissionMode: 'bypassPermissions', mcpServers: { 'files': server } } });
```

### Adding Context-Aware Tools

Create tool factories that close over session-specific data:

```typescript
function createSessionTools(userId: string) {
  return [
    tool('get_user_data', 'Get user data', {}, async () => {
      const data = await db.getUser(userId);  // Closure over userId
      return { content: [{ type: 'text', text: JSON.stringify(data) }] };
    })
  ];
}

// Per-session tools
app.post('/agent', async (req, res) => {
  const tools = createSessionTools(req.session.userId);
  const server = createSdkMcpServer({ name: 'session', version: '1.0.0', tools });
  // ... rest of agent setup
});
```

## Best Practices

### ✅ DO

- **Use Zod schemas** with detailed descriptions
- **Create servers at query time**, not module level
- **Set `permissionMode: 'bypassPermissions'`** for standalone servers
- **Use tool factories** for context-aware tools
- **Write detailed system prompts** (100+ lines)
- **Handle errors** in tool implementations

### ❌ DON'T

- **Don't skip Zod validation** - schemas help Claude use tools correctly
- **Don't use global state** - use closures instead
- **Don't mix module types** - use `"type": "module"` consistently
- **Don't use `interactive` permission mode** in standalone servers

## Authentication

**No configuration required!** The SDK automatically uses Claude Code's authentication. Your agent works seamlessly within Claude Code without any API key setup.

## Debugging

### Enable Tool Logging

```typescript
const messages = query({
  prompt,
  options: {
    systemPrompt,
    mcpServers,
    onToolCall: (name, params) => console.log(`[CALL] ${name}`, params),
    onToolResult: (name, result) => console.log(`[RESULT] ${name}`, result),
  },
});
```

### Test Tools Independently

```typescript
// Test before integrating
const result = await myTool.execute({ param: 'test' });
console.log('Tool output:', result);
```

### Common Issues

**"Claude Code process exited with code 1"**
- Solution: Use `permissionMode: 'bypassPermissions'` for standalone servers

**Tools not being called**
- Check tool descriptions are clear
- Verify system prompt mentions tools
- Ensure schema validation isn't too restrictive

**Import errors**
- Ensure `"type": "module"` in package.json
- Use `.js` extensions in imports (Node16 resolution)

## Reference Files

This skill includes detailed reference documentation:

- **references/patterns.md** - All 4 architecture patterns with complete examples
- **references/tools.md** - Tool creation, composition, factories, subprocess wrappers
- **references/streaming.md** - Event handling, streaming patterns, UI integration
- **references/system-prompts.md** - How to write effective 100+ line prompts
- **references/project-setup.md** - Complete project configuration, directory structures
- **references/api-reference.md** - Official SDK API documentation
- **references/working-examples.md** - Production implementation examples
- **references/troubleshooting.md** - Common issues and solutions

## Next Steps

1. **Quick prototype:** Use the Quick Start example above
2. **Choose pattern:** Select architecture from references/patterns.md
3. **Set up project:** Follow references/project-setup.md
4. **Create tools:** See references/tools.md for patterns
5. **Write system prompt:** Use references/system-prompts.md template
6. **Handle streaming:** Implement patterns from references/streaming.md
7. **Deploy:** Follow project-setup.md deployment guide

## Resources

- **SDK GitHub:** https://github.com/anthropics/anthropic-sdk-typescript
- **Example Projects:** See assets/project-template/ for starter code
- **Community:** Anthropic Developer Discord