# Use and adapt sdk-typescript

Use the documented interfaces and source layout for **sdk-typescript**. The sections below retain the README’s examples and configuration details.

## Core Concepts

### Agents

The `Agent` class is the central orchestrator that manages the interaction loop between users, models, and tools.

```typescript
import { Agent } from '@strands-agents/sdk'

const agent = new Agent({
  systemPrompt: 'You are a helpful assistant.',
})
```
### Model Providers

Switch between model providers easily:

**Amazon Bedrock (Default)**

```typescript
import { Agent, BedrockModel } from '@strands-agents/sdk'

const model = new BedrockModel({
  region: 'us-east-1',
  modelId: 'anthropic.claude-3-5-sonnet-20240620-v1:0',
  maxTokens: 4096,
  temperature: 0.7
})

const agent = new Agent({ model })
```

**OpenAI**

```typescript
import { Agent } from '@strands-agents/sdk'
import { OpenAIModel } from '@strands-agents/sdk/openai'

// Automatically uses process.env.OPENAI_API_KEY and defaults to gpt-4o
const model = new OpenAIModel()

const agent = new Agent({ model })
```

### Streaming Responses

Access responses as they are generated:

```typescript
const agent = new Agent()

console.log('Agent response stream:')
for await (const event of agent.stream('Tell me a story about a brave toaster.')) {
  console.log('[Event]', event.type)
}
```

### Tools

Tools enable agents to interact with external systems and perform actions. Create type-safe tools using Zod schemas:

```typescript
import { Agent, tool } from '@strands-agents/sdk'
import { z } from 'zod'

const weatherTool = tool({
  name: 'get_weather',
  description: 'Get the current weather for a specific location.',
  inputSchema: z.object({
    location: z.string().describe('The city and state, e.g., San Francisco, CA'),
  }),
  callback: (input) => {
    // input is fully typed based on the Zod schema
    return `The weather in ${input.location} is 72°F and sunny.`
  },
})

const agent = new Agent({
  tools: [weatherTool],
})

await agent.invoke('What is the weather in San Francisco?')
```

**Vended Tools**: The SDK includes optional pre-built tools:
- **Notebook Tool**: Manage text-based notebooks for persistent note-taking
- **File Editor Tool**: Perform file system operations (read, write, edit files)
- **HTTP Request Tool**: Make HTTP requests to external APIs

### Structured Output

Get type-safe, validated responses from LLMs by defining the expected output structure with Zod schemas. The agent automatically validates the LLM's response and retries on validation errors:

```typescript
import { Agent } from '@strands-agents/sdk'
import { z } from 'zod'

const PersonSchema = z.object({
  name: z.string().describe('Name of the person'),
  age: z.number().describe('Age of the person'),
  occupation: z.string().describe('Occupation of the person')
})

// Configure structured output at the agent level
const agent = new Agent({ 
  structuredOutputSchema: PersonSchema 
})

const result = await agent.invoke('John Smith is a 30 year-old software engineer')

// result.structuredOutput is fully typed based on the schema
console.log(result.structuredOutput.name) // "John Smith"
console.log(result.structuredOutput.age)  // 30
```

**Error handling**: The agent automatically retries with validation feedback when the LLM provides invalid output. If validation ultimately fails, a `StructuredOutputException` is thrown:

```typescript
import { StructuredOutputException } from '@strands-agents/sdk'

try {
  const result = await agent.invoke('Extract person info...')
  console.log(result.structuredOutput)
} catch (error) {
  if (error instanceof StructuredOutputException) {
    console.error('Validation failed:', error.message)
  }
}
```

### MCP Integration

Seamlessly integrate Model Context Protocol (MCP) servers:

```typescript
import { Agent, McpClient } from "@strands-agents/sdk";
import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";

// Create a client for a local MCP server
const documentationTools = new McpClient({
  transport: new StdioClientTransport({
    command: "uvx",
    args: ["awslabs.aws-documentation-mcp-server@latest"],
  }),
});

const agent = new Agent({
  systemPrompt: "You are a helpful assistant using MCP tools.",
  tools: [documentationTools], // Pass the MCP client directly as a tool source
});

await agent.invoke("Use a random tool from the MCP server.");

await documentationTools.disconnect();
```

---

## Commands in the root manifest

The captured [package.json](https://github.com/Up-to-code/sdk-typescript/blob/HEAD/package.json) declares the following scripts. Run them from the directory containing that manifest.

| Command | Script |
| --- | --- |
| `npm run build` | `tsc --project src/tsconfig.json` |
| `npm run test` | `vitest run --project unit-node` |
| `npm run lint` | `eslint src test/integ` |

## Troubleshoot a local change

1. Reproduce the smallest example from the [quick-start guide](/docs/up-to-code-sdk-typescript/quick-start-guide).
2. Compare required configuration and dependency versions with the README.
3. Check the linked issue tracker for the same error. Include the command, runtime version, and relevant error when reporting a problem; omit credentials.

## Source and help

- [GitHub repository](https://github.com/Up-to-code/sdk-typescript)
- [Original README](https://github.com/Up-to-code/sdk-typescript/blob/main/README.md)
- [Issues and existing reports](https://github.com/Up-to-code/sdk-typescript/issues)
- [Open the project website](https://strandsagents.com)

The catalog identifies the license as **Apache-2.0**. Read the repository license before redistributing source or assets.

This catalog entry is a fork. The README may describe upstream packages, domains, or release procedures; those destinations do not establish a separate release of this fork.