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.

1import { Agent } from '@strands-agents/sdk'
2 
3const agent = new Agent({
4  systemPrompt: 'You are a helpful assistant.',
5})

Model Providers

Switch between model providers easily:

Amazon Bedrock (Default)

1import { Agent, BedrockModel } from '@strands-agents/sdk'
2 
3const model = new BedrockModel({
4  region: 'us-east-1',
5  modelId: 'anthropic.claude-3-5-sonnet-20240620-v1:0',
6  maxTokens: 4096,
7  temperature: 0.7
8})
9 
10const agent = new Agent({ model })

OpenAI

1import { Agent } from '@strands-agents/sdk'
2import { OpenAIModel } from '@strands-agents/sdk/openai'
3 
4// Automatically uses process.env.OPENAI_API_KEY and defaults to gpt-4o
5const model = new OpenAIModel()
6 
7const agent = new Agent({ model })

Streaming Responses

Access responses as they are generated:

1const agent = new Agent()
2 
3console.log('Agent response stream:')
4for await (const event of agent.stream('Tell me a story about a brave toaster.')) {
5  console.log('[Event]', event.type)
6}

Tools

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

1import { Agent, tool } from '@strands-agents/sdk'
2import { z } from 'zod'
3 
4const weatherTool = tool({
5  name: 'get_weather',
6  description: 'Get the current weather for a specific location.',
7  inputSchema: z.object({
8    location: z.string().describe('The city and state, e.g., San Francisco, CA'),
9  }),
10  callback: (input) => {
11    // input is fully typed based on the Zod schema
12    return `The weather in ${input.location} is 72°F and sunny.`
13  },
14})
15 
16const agent = new Agent({
17  tools: [weatherTool],
18})
19 
20await 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:

1import { Agent } from '@strands-agents/sdk'
2import { z } from 'zod'
3 
4const PersonSchema = z.object({
5  name: z.string().describe('Name of the person'),
6  age: z.number().describe('Age of the person'),
7  occupation: z.string().describe('Occupation of the person')
8})
9 
10// Configure structured output at the agent level
11const agent = new Agent({ 
12  structuredOutputSchema: PersonSchema 
13})
14 
15const result = await agent.invoke('John Smith is a 30 year-old software engineer')
16 
17// result.structuredOutput is fully typed based on the schema
18console.log(result.structuredOutput.name) // "John Smith"
19console.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:

1import { StructuredOutputException } from '@strands-agents/sdk'
2 
3try {
4  const result = await agent.invoke('Extract person info...')
5  console.log(result.structuredOutput)
6} catch (error) {
7  if (error instanceof StructuredOutputException) {
8    console.error('Validation failed:', error.message)
9  }
10}

MCP Integration

Seamlessly integrate Model Context Protocol (MCP) servers:

1import { Agent, McpClient } from "@strands-agents/sdk";
2import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
3 
4// Create a client for a local MCP server
5const documentationTools = new McpClient({
6  transport: new StdioClientTransport({
7    command: "uvx",
8    args: ["awslabs.aws-documentation-mcp-server@latest"],
9  }),
10});
11 
12const agent = new Agent({
13  systemPrompt: "You are a helpful assistant using MCP tools.",
14  tools: [documentationTools], // Pass the MCP client directly as a tool source
15});
16 
17await agent.invoke("Use a random tool from the MCP server.");
18 
19await documentationTools.disconnect();

Commands in the root manifest

The captured 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

Reproduce the smallest example from the quick-start guide.
Compare required configuration and dependency versions with the README.
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

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.