A collection of comprehensive examples that demonstrate how to build AI agents in TypeScript with ADK-TS
Agent Building • Tool Integration • Memory Systems • Advanced Feature
This directory contains a collection of comprehensive examples that demonstrate how to build AI agents in TypeScript with ADK-TS. You can use these examples to learn how to build AI agents, integrate tools, manage memory, and implement advanced features.
Before running the examples, here's what you need:
- Node.js 22.0+ (or as specified in the
package.jsonfile) - API Keys for your chosen LLM provider(s)
Note: this project uses pnpm as the package manager. You can use other package managers, but to have a better experience, please install pnpm globally on your system.
- Clone the Repository and Install the Dependencies
git clone https://github.com/IQAIcom/adk-ts.git
cd adk-ts
pnpm install- Build the ADK-TS Package
For the examples to work correctly, you need to build the core ADK-TS package first. This step compiles the TypeScript code and prepares the necessary files.
pnpm build- Configure Environment Variables
Create a .env file in the examples directory (not in the root folder) and add your API keys and optional model configuration. This file is used to set environment variables that the examples will use.
# apps/examples/.env
# Optional: Specify which model to use
LLM_MODEL=your_model_name
# Required: At least one API key
GOOGLE_API_KEY=your_google_api_key
OPENAI_API_KEY=your_openai_api_key
ANTHROPIC_API_KEY=your_anthropic_api_keyThe default LLM is Google Gemini. You can get a Google API key from Google AI Studio. If you want to use a different model, you can specify it in the .env file using the LLM_MODEL variable or update it directly in the example code.
Note: Some examples require additional configuration or dependencies. Please check the
.env.examplefile for specific instructions.
- Run Examples
To explore the examples, you can either browse all available examples or run a specific one directly:
cd apps/examples
# Interactive mode - browse and select an example
pnpm start
# Or run a specific example directly
pnpm start --name 01-getting-started
pnpm start --name 06-mcp-and-integrationsWe have 9 comprehensive examples that cover the complete ADK-TS feature set, organized in a logical learning progression from basic concepts to advanced implementations:
| Example | Description | Key Concepts |
|---|---|---|
| 01-getting-started | Basic agent setup and folder structure | AgentBuilder basics, Zod schemas, structured responses |
| 02-tools-and-state | Custom tools with state management | Tool creation, state persistence, system instructions |
| 03-multi-agent-systems | Multi-agent systems and coordination | Sub-agents, agent delegation, specialized roles |
| Example | Description | Key Concepts |
|---|---|---|
| 04-persistence-and-sessions | Database integration, artifacts, and session rewind | Session persistence, artifacts, event compaction, time-travel |
| 05-planning-and-code-execution | Planning and code execution capabilities | PlanReActPlanner, BuiltInCodeExecutor, Python sandbox |
| Example | Description | Key Concepts |
|---|---|---|
| 06-mcp-and-integrations | Model Context Protocol with custom and external servers | MCP servers, sampling, custom sampling handler with routing, Coingecko integration |
| 07-guardrails-and-evaluation | Safety guardrails and agent evaluation | Plugins, lifecycle hooks, content filtering, AgentEvaluator |
| 08-observability-and-plugins | Monitoring, tracing, and metrics | OpenTelemetry, Langfuse integration, observability |
| 09-scheduling | Recurring agent execution on a schedule | AgentScheduler, cron/interval jobs, callbacks, event listeners |
If you would like to add examples or improve existing ones, please check out our Contributing Guide for details on how to get started.
💡 Pro Tip: Follow the examples in order (01-09) for a structured learning path, or jump to specific examples based on your needs. Start with 01-getting-started to understand the basics, then explore advanced features like multi-agent systems, MCP integrations, guardrails, observability, and scheduling!
