Getting started

Installation

The fastest path is the CLI, which scaffolds a runnable project with no manual wiring. Adding samai-sdk to an existing project is just as direct.

Scaffold a new project

npx samai-sdk create generates a working package.json, tsconfig.json, .env.example, and a src/index.ts with one agent and one tool already wired to the provider you pick.

terminal

npx samai-sdk create my-agent --provider anthropic
cd my-agent && npm install && cp .env.example .env   # add your API key
npm start

--provider accepts anthropic (default), openai, groq, or ollama — the last one needs no API key at all, see Providers.

Add to an existing project

terminal

npm install samai-sdk

# plus whichever provider SDK(s) you actually use:
npm install openai                    # openai(), groq(), mistral(), ollama(), azureOpenAI()
npm install @anthropic-ai/sdk         # anthropic()
npm install @google/generative-ai     # google()
npm install @aws-sdk/client-bedrock-runtime  # bedrock()

Provider SDKs are peer dependencies — install only the ones you actually use. They're loaded lazily, so nothing you don't use ends up in your bundle.

Optional dependencies

Also loaded lazily, and only needed for the specific feature they back:

terminal

npm install ioredis                    # RedisSessionStore
npm install better-sqlite3             # SqliteSessionStore
npm install react                      # the samai-sdk/react useAgent() hook
npm install @modelcontextprotocol/sdk  # createMCPClient()
npm install ws                         # createRealtimeSession() on Node < 22
npm install valibot @valibot/to-json-schema  # Standard Schema tools/output

Note

groq(), mistral(), ollama(), and azureOpenAI() all reuse the openai package pointed at a different baseURL — that's why they share it as a peer dependency instead of needing their own.