https://github.com/strands-agents/sdk-typescript

A model-driven approach to building AI agents in just a few lines of code.
https://github.com/strands-agents/sdk-typescript

agents ai autonomous-agents bedrock genai javascript llm machine-learning mcp multi-agent-systems openai opentelemetry strands-agents typescript

Last synced: 12 days ago
JSON representation

A model-driven approach to building AI agents in just a few lines of code.

Host: GitHub
URL: https://github.com/strands-agents/sdk-typescript
Owner: strands-agents
License: apache-2.0
Created: 2025-09-19T00:13:25.000Z (6 months ago)
Default Branch: main
Last Pushed: 2026-03-06T21:41:29.000Z (17 days ago)
Last Synced: 2026-03-06T22:35:27.198Z (17 days ago)
Topics: agents, ai, autonomous-agents, bedrock, genai, javascript, llm, machine-learning, mcp, multi-agent-systems, openai, opentelemetry, strands-agents, typescript
Language: TypeScript
Homepage: https://strandsagents.com
Size: 1.41 MB
Stars: 511
Watchers: 7
Forks: 65
Open Issues: 96
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Notice: NOTICE
- Agents: AGENTS.md

Awesome Lists containing this project

awesome-strands-agents - TypeScript SDK - agents/sdk-typescript](https://github.com/strands-agents/sdk-typescript) | Official Resources | (Community Projects / For PyPI Packages)
awesome-mcp - strands-agents/sdk-typescript - Strands Agents SDK for TypeScript is a model-driven, type-safe framework for building and running AI agents with native support for the Model Context Protocol (MCP) and multiple model providers. (MCP Frameworks and libraries / TypeScript)
awesome-ChatGPT-repositories - sdk-typescript - A model-driven approach to building AI agents in just a few lines of code. (The latest additions 🎉)

README

          


  

    

      

    

  


  


    Strands Agents - TypeScript SDK

  


  


    A model-driven approach to building AI agents in TypeScript/JavaScript.

  


  


    

    

    

    

    

  

  

  

    Documentation

    ◆ Samples

    ◆ Python SDK

    ◆ Tools

    ◆ Agent Builder

    ◆ MCP Server

  



---

## Overview

Strands Agents is a simple yet powerful SDK that takes a model-driven approach to building and running AI agents. The TypeScript SDK brings key features from the Python Strands framework to Node.js environments, enabling type-safe agent development for everything from simple assistants to complex workflows.

### Key Features

- **🪶 Lightweight & Flexible**: Simple agent loop that works seamlessly in Node.js and browser environments

- **🔒 Type-Safe Tools**: Define tools easily using Zod schemas for robust input validation and type inference

- **📋 Structured Output**: Get type-safe, validated responses from LLMs using Zod schemas with automatic retry on validation errors

- **🔌 Model Agnostic**: First-class support for Amazon Bedrock and OpenAI, with extensible architecture for custom providers

- **🔗 Built-in MCP**: Native support for Model Context Protocol (MCP) clients, enabling access to external tools and servers

- **⚡ Streaming Support**: Real-time response streaming for better user experience

- **🎣 Extensible Hooks**: Lifecycle hooks for monitoring and customizing agent behavior

- **💬 Conversation Management**: Flexible strategies for managing conversation history and context windows

---

## Quick Start

### Installation

Ensure you have **[Node.js 20+](https://nodejs.org/)** installed, then:

```bash

npm install @strands-agents/sdk

```

### Basic Usage

```typescript

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

// Create agent (uses default Amazon Bedrock provider)

const agent = new Agent()

// Invoke

const result = await agent.invoke('What is the square root of 1764?')

console.log(result)

```

> **Note**: For the default Amazon Bedrock model provider, you'll need AWS credentials configured and model access enabled for Claude 4.5 Sonnet in your region.

---

## 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();

```

---

## Documentation

For detailed guidance, tutorials, and concept overviews, please visit:

- **[Official Documentation](https://strandsagents.com/)**: Comprehensive guides and tutorials

- **[API Reference](https://strandsagents.com/latest/documentation/docs/api-reference/typescript/)**: Complete API documentation

- **[Examples](./examples/)**: Sample applications

- **[Contributing Guide](CONTRIBUTING.md)**: Development setup and guidelines

---

## Contributing ❤️

We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details on:

- Development setup and environment

- Testing and code quality standards

- Pull request process

- Code of Conduct

- Security issue reporting

---

## License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

---

## Security

See [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information on reporting security issues.

---

## ⚠️ Preview Status

Strands Agents is currently in public preview. During this period:

- APIs may change as we refine the SDK

- We welcome feedback and contributions