{"id":35094042,"url":"https://github.com/strands-agents/sdk-typescript","last_synced_at":"2026-03-11T20:04:04.622Z","repository":{"id":327445057,"uuid":"1059784055","full_name":"strands-agents/sdk-typescript","owner":"strands-agents","description":"A model-driven approach to building AI agents in just a few lines of code. ","archived":false,"fork":false,"pushed_at":"2026-03-06T21:41:29.000Z","size":1478,"stargazers_count":511,"open_issues_count":96,"forks_count":65,"subscribers_count":7,"default_branch":"main","last_synced_at":"2026-03-06T22:35:27.198Z","etag":null,"topics":["agents","ai","autonomous-agents","bedrock","genai","javascript","llm","machine-learning","mcp","multi-agent-systems","openai","opentelemetry","strands-agents","typescript"],"latest_commit_sha":null,"homepage":"https://strandsagents.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/strands-agents.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","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":"NOTICE","maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-19T00:13:25.000Z","updated_at":"2026-03-06T21:34:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/strands-agents/sdk-typescript","commit_stats":null,"previous_names":["strands-agents/sdk-typescript"],"tags_count":13,"template":false,"template_full_name":"amazon-archives/__template_Apache-2.0","purl":"pkg:github/strands-agents/sdk-typescript","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strands-agents%2Fsdk-typescript","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strands-agents%2Fsdk-typescript/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strands-agents%2Fsdk-typescript/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strands-agents%2Fsdk-typescript/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/strands-agents","download_url":"https://codeload.github.com/strands-agents/sdk-typescript/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/strands-agents%2Fsdk-typescript/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30395146,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T18:46:22.935Z","status":"ssl_error","status_checked_at":"2026-03-11T18:46:17.045Z","response_time":84,"last_error":"SSL_read: 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","autonomous-agents","bedrock","genai","javascript","llm","machine-learning","mcp","multi-agent-systems","openai","opentelemetry","strands-agents","typescript"],"created_at":"2025-12-27T15:04:24.310Z","updated_at":"2026-03-11T20:04:04.616Z","avatar_url":"https://github.com/strands-agents.png","language":"TypeScript","readme":"\u003cdiv align=\"center\"\u003e\n  \u003cdiv\u003e\n    \u003ca href=\"https://strandsagents.com\"\u003e\n      \u003cimg src=\"https://strandsagents.com/latest/assets/logo-github.svg\" alt=\"Strands Agents\" width=\"55px\" height=\"105px\"\u003e\n    \u003c/a\u003e\n  \u003c/div\u003e\n\n  \u003ch1\u003e\n    Strands Agents - TypeScript SDK\n  \u003c/h1\u003e\n\n  \u003ch2\u003e\n    A model-driven approach to building AI agents in TypeScript/JavaScript.\n  \u003c/h2\u003e\n\n  \u003cdiv align=\"center\"\u003e\n    \u003ca href=\"https://github.com/strands-agents/sdk-typescript/graphs/commit-activity\"\u003e\u003cimg alt=\"GitHub commit activity\" src=\"https://img.shields.io/github/commit-activity/m/strands-agents/sdk-typescript\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/strands-agents/sdk-typescript/issues\"\u003e\u003cimg alt=\"GitHub open issues\" src=\"https://img.shields.io/github/issues/strands-agents/sdk-typescript\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/strands-agents/sdk-typescript/pulls\"\u003e\u003cimg alt=\"GitHub open pull requests\" src=\"https://img.shields.io/github/issues-pr/strands-agents/sdk-typescript\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://github.com/strands-agents/sdk-typescript/blob/main/LICENSE\"\u003e\u003cimg alt=\"License\" src=\"https://img.shields.io/github/license/strands-agents/sdk-typescript\"/\u003e\u003c/a\u003e\n    \u003ca href=\"https://www.npmjs.com/package/@strands-agents/sdk\"\u003e\u003cimg alt=\"NPM Version\" src=\"https://img.shields.io/npm/v/@strands-agents/sdk\"/\u003e\u003c/a\u003e\n  \u003c/div\u003e\n  \n  \u003cp\u003e\n    \u003ca href=\"https://strandsagents.com/\"\u003eDocumentation\u003c/a\u003e\n    ◆ \u003ca href=\"https://github.com/strands-agents/samples\"\u003eSamples\u003c/a\u003e\n    ◆ \u003ca href=\"https://github.com/strands-agents/sdk-python\"\u003ePython SDK\u003c/a\u003e\n    ◆ \u003ca href=\"https://github.com/strands-agents/tools\"\u003eTools\u003c/a\u003e\n    ◆ \u003ca href=\"https://github.com/strands-agents/agent-builder\"\u003eAgent Builder\u003c/a\u003e\n    ◆ \u003ca href=\"https://github.com/strands-agents/mcp-server\"\u003eMCP Server\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/div\u003e\n\n---\n\n## Overview\n\nStrands 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.\n\n### Key Features\n\n- **🪶 Lightweight \u0026 Flexible**: Simple agent loop that works seamlessly in Node.js and browser environments\n- **🔒 Type-Safe Tools**: Define tools easily using Zod schemas for robust input validation and type inference\n- **📋 Structured Output**: Get type-safe, validated responses from LLMs using Zod schemas with automatic retry on validation errors\n- **🔌 Model Agnostic**: First-class support for Amazon Bedrock and OpenAI, with extensible architecture for custom providers\n- **🔗 Built-in MCP**: Native support for Model Context Protocol (MCP) clients, enabling access to external tools and servers\n- **⚡ Streaming Support**: Real-time response streaming for better user experience\n- **🎣 Extensible Hooks**: Lifecycle hooks for monitoring and customizing agent behavior\n- **💬 Conversation Management**: Flexible strategies for managing conversation history and context windows\n\n---\n\n## Quick Start\n\n### Installation\n\nEnsure you have **[Node.js 20+](https://nodejs.org/)** installed, then:\n\n```bash\nnpm install @strands-agents/sdk\n```\n\n### Basic Usage\n\n```typescript\nimport { Agent } from '@strands-agents/sdk'\n\n// Create agent (uses default Amazon Bedrock provider)\nconst agent = new Agent()\n\n// Invoke\nconst result = await agent.invoke('What is the square root of 1764?')\nconsole.log(result)\n```\n\n\u003e **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.\n\n---\n\n## Core Concepts\n\n### Agents\n\nThe `Agent` class is the central orchestrator that manages the interaction loop between users, models, and tools.\n\n```typescript\nimport { Agent } from '@strands-agents/sdk'\n\nconst agent = new Agent({\n  systemPrompt: 'You are a helpful assistant.',\n})\n```\n### Model Providers\n\nSwitch between model providers easily:\n\n**Amazon Bedrock (Default)**\n\n```typescript\nimport { Agent, BedrockModel } from '@strands-agents/sdk'\n\nconst model = new BedrockModel({\n  region: 'us-east-1',\n  modelId: 'anthropic.claude-3-5-sonnet-20240620-v1:0',\n  maxTokens: 4096,\n  temperature: 0.7\n})\n\nconst agent = new Agent({ model })\n```\n\n**OpenAI**\n\n```typescript\nimport { Agent } from '@strands-agents/sdk'\nimport { OpenAIModel } from '@strands-agents/sdk/openai'\n\n// Automatically uses process.env.OPENAI_API_KEY and defaults to gpt-4o\nconst model = new OpenAIModel()\n\nconst agent = new Agent({ model })\n```\n\n### Streaming Responses\n\nAccess responses as they are generated:\n\n```typescript\nconst agent = new Agent()\n\nconsole.log('Agent response stream:')\nfor await (const event of agent.stream('Tell me a story about a brave toaster.')) {\n  console.log('[Event]', event.type)\n}\n```\n\n### Tools\n\nTools enable agents to interact with external systems and perform actions. Create type-safe tools using Zod schemas:\n\n```typescript\nimport { Agent, tool } from '@strands-agents/sdk'\nimport { z } from 'zod'\n\nconst weatherTool = tool({\n  name: 'get_weather',\n  description: 'Get the current weather for a specific location.',\n  inputSchema: z.object({\n    location: z.string().describe('The city and state, e.g., San Francisco, CA'),\n  }),\n  callback: (input) =\u003e {\n    // input is fully typed based on the Zod schema\n    return `The weather in ${input.location} is 72°F and sunny.`\n  },\n})\n\nconst agent = new Agent({\n  tools: [weatherTool],\n})\n\nawait agent.invoke('What is the weather in San Francisco?')\n```\n\n**Vended Tools**: The SDK includes optional pre-built tools:\n- **Notebook Tool**: Manage text-based notebooks for persistent note-taking\n- **File Editor Tool**: Perform file system operations (read, write, edit files)\n- **HTTP Request Tool**: Make HTTP requests to external APIs\n\n\n### Structured Output\n\nGet 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:\n\n```typescript\nimport { Agent } from '@strands-agents/sdk'\nimport { z } from 'zod'\n\nconst PersonSchema = z.object({\n  name: z.string().describe('Name of the person'),\n  age: z.number().describe('Age of the person'),\n  occupation: z.string().describe('Occupation of the person')\n})\n\n// Configure structured output at the agent level\nconst agent = new Agent({ \n  structuredOutputSchema: PersonSchema \n})\n\nconst result = await agent.invoke('John Smith is a 30 year-old software engineer')\n\n// result.structuredOutput is fully typed based on the schema\nconsole.log(result.structuredOutput.name) // \"John Smith\"\nconsole.log(result.structuredOutput.age)  // 30\n```\n\n**Error handling**: The agent automatically retries with validation feedback when the LLM provides invalid output. If validation ultimately fails, a `StructuredOutputException` is thrown:\n\n```typescript\nimport { StructuredOutputException } from '@strands-agents/sdk'\n\ntry {\n  const result = await agent.invoke('Extract person info...')\n  console.log(result.structuredOutput)\n} catch (error) {\n  if (error instanceof StructuredOutputException) {\n    console.error('Validation failed:', error.message)\n  }\n}\n```\n\n\n### MCP Integration\n\nSeamlessly integrate Model Context Protocol (MCP) servers:\n\n```typescript\nimport { Agent, McpClient } from \"@strands-agents/sdk\";\nimport { StdioClientTransport } from \"@modelcontextprotocol/sdk/client/stdio.js\";\n\n// Create a client for a local MCP server\nconst documentationTools = new McpClient({\n  transport: new StdioClientTransport({\n    command: \"uvx\",\n    args: [\"awslabs.aws-documentation-mcp-server@latest\"],\n  }),\n});\n\nconst agent = new Agent({\n  systemPrompt: \"You are a helpful assistant using MCP tools.\",\n  tools: [documentationTools], // Pass the MCP client directly as a tool source\n});\n\nawait agent.invoke(\"Use a random tool from the MCP server.\");\n\nawait documentationTools.disconnect();\n```\n\n---\n\n## Documentation\n\nFor detailed guidance, tutorials, and concept overviews, please visit:\n\n- **[Official Documentation](https://strandsagents.com/)**: Comprehensive guides and tutorials\n- **[API Reference](https://strandsagents.com/latest/documentation/docs/api-reference/typescript/)**: Complete API documentation\n- **[Examples](./examples/)**: Sample applications\n- **[Contributing Guide](CONTRIBUTING.md)**: Development setup and guidelines\n\n---\n\n## Contributing ❤️\n\nWe welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for details on:\n\n- Development setup and environment\n- Testing and code quality standards\n- Pull request process\n- Code of Conduct\n- Security issue reporting\n\n---\n\n## License\n\nThis project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.\n\n---\n\n## Security\n\nSee [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information on reporting security issues.\n\n---\n\n## ⚠️ Preview Status\n\nStrands Agents is currently in public preview. During this period:\n- APIs may change as we refine the SDK\n- We welcome feedback and contributions\n","funding_links":[],"categories":["Community Projects","📚 Projects (1974 total)","MCP Frameworks and libraries","The latest additions 🎉"],"sub_categories":["For PyPI Packages","MCP Servers","TypeScript"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrands-agents%2Fsdk-typescript","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstrands-agents%2Fsdk-typescript","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstrands-agents%2Fsdk-typescript/lists"}