Skip to content

examples

Directory actions

More options

Directory actions

More options

Latest commit

 

History

History

examples

README.md

📚 Tawk Agents SDK - Examples

Complete collection of examples demonstrating all features of the SDK, organized from basic to advanced.

🎯 Quick Start

# Install dependencies
npm install

# Run any example
npx tsx 01-basic/01-simple-agent.ts

# Or use the universal runner
npx tsx run.ts 01

📖 Examples by Level

01-basic/ - Getting Started

Perfect for beginners. Learn the fundamentals.

File Description Key Concepts
01-simple-agent.ts Basic conversational agent Agent creation, run()
02-agent-with-tools.ts Adding capabilities Tools, parallel execution
03-multi-agent.ts Agent coordination Handoffs, specialization
04-sessions.ts Conversation memory Sessions, context

02-intermediate/ - Core Features

Intermediate features for production apps.

File Description Key Concepts
05-guardrails.ts Safety and validation Input/output guardrails
06-streaming.ts Real-time responses Streaming, events
07-tracing.ts Observability Langfuse, debugging

03-advanced/ - Advanced Features

Advanced patterns and integrations.

File Description Key Concepts
09-embeddings-rag.ts Semantic search Embeddings, RAG
10-vision.ts Image understanding Vision models, multimodal
11-toon-format.ts Token optimization TOON format, efficiency
12-mcp-integration.ts Model Context Protocol MCP servers, tool discovery
13-dynamic-approvals.ts Human-in-the-loop Approvals, safety
14-multi-agent-research.ts Complex coordination Research patterns

04-production/ - Production Ready

Complete production-ready systems.

File Description Key Concepts
15-ecommerce-system.ts E-commerce assistant Full system, workflows
16-complete-showcase.ts All features Comprehensive demo

05-patterns/ - Design Patterns

Proven agentic patterns and architectures.

File Description Key Concepts
17-agentic-patterns.ts Agentic design patterns Architecture, best practices

🎓 Learning Path

Beginner Path (30 minutes)

  1. 01-simple-agent.ts → Learn basic agent creation
  2. 02-agent-with-tools.ts → Add capabilities
  3. 03-multi-agent.ts → Agent coordination
  4. 04-sessions.ts → Add memory

Intermediate Path (1 hour)

  1. 05-guardrails.ts → Add safety
  2. 06-streaming.ts → Real-time UX
  3. 07-tracing.ts → Observability

Advanced Path (2+ hours)

  1. 09-embeddings-rag.ts → Semantic search
  2. 12-mcp-integration.ts → Tool discovery
  3. 13-dynamic-approvals.ts → HITL safety
  4. 15-ecommerce-system.ts → Full system

🚀 Running Examples

Option 1: Direct Execution

npx tsx 01-basic/01-simple-agent.ts

Option 2: Universal Runner

# Run by number
npx tsx run.ts 01

# Run by name
npx tsx run.ts simple-agent

# List all examples
npx tsx run.ts --list

Option 3: Watch Mode

# Auto-reload on changes
npx tsx watch 01-basic/01-simple-agent.ts

⚙️ Configuration

Environment Variables

Create a .env file:

# Required
OPENAI_API_KEY=sk-...

# Optional
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_AI_API_KEY=...
LANGFUSE_PUBLIC_KEY=pk-...
LANGFUSE_SECRET_KEY=sk-...

📚 Additional Resources

Reference Files

  • all-features.ts - Comprehensive feature reference
  • run.ts - Universal example runner
  • STRUCTURE.md - Detailed structure documentation

Documentation

🎯 Quick Reference

Most Common Tasks

Create a basic agent:

const agent = new Agent({
  name: 'Assistant',
  model: openai('gpt-4o-mini'),
  instructions: 'You are helpful.',
});
const result = await run(agent, 'Hello!');

Add tools:

const tool = tool({
  description: 'Calculate',
  inputSchema: z.object({ expr: z.string() }),
  execute: async ({ expr }) => eval(expr)
});

Multi-agent coordination:

const coordinator = new Agent({
  subagents: [specialist1, specialist2]
});

Add memory:

const session = new MemorySession('user-id');
await run(agent, 'Hello', { session });

🤝 Contributing

Want to add an example? Follow the structure:

  1. Create file with number prefix (e.g., 08-my-example.ts)
  2. Add clear comments explaining what and why
  3. Keep it focused on ONE concept
  4. Update this README

📝 Notes

  • All examples use TypeScript
  • Examples are self-contained and runnable
  • Check utils/ folder for shared helpers
  • Examples use gpt-4o-mini by default (change if needed)

Ready to start? Begin with 01-basic/01-simple-agent.ts! 🚀