# Sdk Typescript

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-strands-agents-sdk-typescript`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [strands-agents](https://agentstack.voostack.com/s/strands-agents)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [strands-agents](https://github.com/strands-agents)
- **Source:** https://github.com/strands-agents/sdk-typescript
- **Website:** https://strandsagents.com

## Install

```sh
agentstack add mcp-strands-agents-sdk-typescript
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

### :warning: This repository has been archived

**The TypeScript SDK has moved to the [strands-agents/harness-sdk](https://github.com/strands-agents/harness-sdk) monorepo.**

The source code is now under [`strands-ts/`](https://github.com/strands-agents/harness-sdk/tree/main/strands-ts). All new development, issues, and pull requests should go there.

---

  
    
      
    
  

  
    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
- **🤝 Multi-Agent Orchestration**: Graph and Swarm patterns for coordinating multiple agents

---

## 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 Sonnet 4 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/models/openai'

// Automatically uses process.env.OPENAI_API_KEY and defaults to gpt-5.4
const model = new OpenAIModel({ api: 'chat' })

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 `StructuredOutputError` is thrown:

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

try {
  const result = await agent.invoke('Extract person info...')
  console.log(result.structuredOutput)
} catch (error) {
  if (error instanceof StructuredOutputError) {
    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();
```

### Multi-Agent Orchestration

Coordinate multiple agents using built-in orchestration patterns.

**Graph** — You define a deterministic execution plan. Agents run as nodes in a directed graph, with edges controlling execution order. Parallel execution is supported, and downstream nodes run once all dependencies complete.

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

const model = new BedrockModel({ maxTokens: 1024 })

const researcher = new Agent({
  model,
  id: 'researcher',
  systemPrompt: 'Research the topic and provide key facts.',
})

const writer = new Agent({
  model,
  id: 'writer',
  systemPrompt: 'Rewrite the research into a polished paragraph.',
})

const graph = new Graph({
  nodes: [researcher, writer],
  edges: [['researcher', 'writer']],
})

const result = await graph.invoke('What is the largest ocean?')
```

**Swarm** — The agents decide the routing. Each agent chooses whether to hand off to another agent or produce a final response, making the execution path dynamic and model-driven.

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

const model = new BedrockModel({ maxTokens: 1024 })

const researcher = new Agent({
  model,
  id: 'researcher',
  description: 'Researches a topic and gathers key facts.',
  systemPrompt: 'Research the answer, then hand off to the writer.',
})

const writer = new Agent({
  model,
  id: 'writer',
  description: 'Writes a polished final answer.',
  systemPrompt: 'Write the final answer. Do not hand off.',
})

const swarm = new Swarm({
  nodes: [researcher, writer],
  start: 'researcher',
  maxSteps: 4,
})

const result = await swarm.invoke('What is the largest ocean?')
```

Both patterns support streaming via `.stream()` for real-time access to handoff and node execution events. See the [examples](./strands-ts/examples/) directory for complete working samples.

---

## Documentation

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

- **[Official Documentation](https://strandsagents.com/)**: Comprehensive guides and tutorials
- **[API Reference](https://strandsagents.com/docs/api/typescript/)**: Complete API documentation
- **[Examples](./strands-ts/examples/)**: Sample applications
  - **[First Agent](./strands-ts/examples/first-agent/)**: Basic Node.js agent
  - **[MCP](./strands-ts/examples/mcp/)**: MCP integration example
  - **[Browser Agent](./strands-ts/examples/browser-agent/)**: Browser-based agent with DOM manipulation

- **[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

---

## Stay in touch with the team
Come meet the Strands team and other users on [**Discord**](https://discord.com/invite/strands)

---

## License

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

---

## Security

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [strands-agents](https://github.com/strands-agents)
- **Source:** [strands-agents/sdk-typescript](https://github.com/strands-agents/sdk-typescript)
- **License:** Apache-2.0
- **Homepage:** https://strandsagents.com

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-strands-agents-sdk-typescript
- Seller: https://agentstack.voostack.com/s/strands-agents
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.