{"slug": "building-ai-agents-with-the-typescript-agent-development-kit-adk", "title": "Building AI Agents with the TypeScript Agent Development Kit (ADK)", "summary": "Google's Agent Development Kit (ADK) for TypeScript is now available as a flexible, model-agnostic framework for building and deploying AI agents. A sample 'Hello World' agent demonstrates local tools for weather and time, with full type safety via TypeScript and Zod schema validation. The ADK supports Node.js and browser runtimes, and is published on npm as @google/adk.", "body_md": "This tutorial builds a starter \"Hello World\" style agent using TypeScript and the native TypeScript version of the Agent Development Kit (ADK).\n\nThe full sample project is available on GitHub:\n\nA minimal weather and time agent built with Google's\n[Agent Development Kit for TypeScript](https://github.com/google/adk-js).\n\n```\nnpm install\ncp .env.example .env\n```\n\nEdit `.env`\n\nand choose one authentication method:\n\n`GOOGLE_API_KEY`\n\n`GOOGLE_GENAI_USE_VERTEXAI=TRUE`\n\n,\n`GOOGLE_CLOUD_PROJECT`\n\n, and `GOOGLE_CLOUD_LOCATION`\n\n, then run\n`gcloud auth application-default login`\n\nNever commit `.env`\n\n.\n\n```\n# Interactive terminal\nnpm start\n\n# ADK development UI\nnpm run web\n\n# Type-check and run unit tests\nnpm run check\n```\n\nThe ADK CLI can also be called directly:\n\n```\nnpx adk run src/agent.ts\nnpx adk web\n```\n\nThe agent source is in `src/agent.ts`\n\n. Its two local tools preserve the original\nsample behavior: weather and local time are available for New York, while other\ncities return a clear unsupported-city result.\n\nTypeScript is a strongly typed programming language built on top of JavaScript, maintained by Microsoft. It compiles to plain JavaScript and runs anywhere JavaScript runs — including Node.js, which is what the ADK for TypeScript targets. The static type system pairs naturally with agent development: tool parameters, tool results, and agent configuration are all checked at compile time, before the model ever sees them.\n\nThe ADK for TypeScript requires **Node.js 20 or newer**. If Node.js is not installed in your environment, the Node Version Manager (`nvm`\n\n) is the easiest way to install and manage versions:\n\nInstall and activate a current Node.js release:\n\n```\nnvm install --lts\nnvm use --lts\n```\n\nYou can validate the installation with the version command:\n\n```\nnode --version\n# v22.x\n```\n\nThe Agent Development Kit (ADK) is a flexible and modular framework for **developing and deploying AI agents**. While optimized for Gemini and the Google ecosystem, ADK is **model-agnostic**, **deployment-agnostic**, and built for **compatibility with other frameworks**.\n\nGoogle provides full documentation on the ADK here:\n\nGoogle provides the source to the complete TypeScript version of the ADK project:\n\nAgent Development Kit (ADK) is a flexible and modular framework for building, deploying, and orchestrating AI agent workflows, from simple tasks to complex multi-agent systems. Define agent behavior, orchestration, and tool use directly in code, enabling robust debugging, versioning, and deployment anywhere.\n\nThe TypeScript version of ADK is built for the Node.js and browser ecosystems, with full type safety, Zod schema validation, and support for ESM, CommonJS, and web runtimes.\n\n**Code-First TypeScript**: Define agent logic, tools, and orchestration with\nfull type safety. Tool parameters support Zod v3 and v4 schemas with\ncompile-time type inference.\n\n**Browser and Server**: Ships ESM, CommonJS, and web bundles. Run agents in\nNode.js or directly in the browser.\n\n**Rich**…\n\nThe ADK is published to npm as [ @google/adk](https://www.npmjs.com/package/@google/adk), with the development tooling in\n\n`@google/adk-devtools`\n\n. This tutorial uses If not using Application Default Credentials (ADC), you will need a Gemini API key. You can get a Gemini key from Google AI Studio:\n\nOnce Node.js is installed, clone the sample repo and run the `init.sh`\n\nscript. It installs the npm dependencies and creates a starter `.env`\n\nfile:\n\n```\ngit clone https://github.com/xbill9/adk-hello-world-typescript\ncd adk-hello-world-typescript\nsource init.sh\n```\n\nOutput:\n\n```\nCreated .env from .env.example. Add your credentials before running the agent.\nSetup complete. Run: npm start\n```\n\nEdit `.env`\n\nand choose one authentication method:\n\n`GOOGLE_API_KEY`\n\n`GOOGLE_GENAI_USE_VERTEXAI=TRUE`\n\n, `GOOGLE_CLOUD_PROJECT`\n\n, and `GOOGLE_CLOUD_LOCATION`\n\n, then authenticate with ADC:\n\n```\ngcloud auth login\ngcloud auth application-default login\n```\n\nNote:Never commit`.env`\n\n— it is already listed in`.gitignore`\n\n.\n\nIf your Application Default Credentials expire or your Google Cloud authentication expires, re-authenticate with:\n\n```\ngcloud auth login\ngcloud auth application-default login\n```\n\nAnother common issue is missing environment variables. The agent loads `.env`\n\nautomatically via `dotenv`\n\n, and the `set_env.sh`\n\nscript is provided for shell commands that need the same values:\n\n```\nsource set_env.sh\n```\n\nThe entire agent lives in a single file — `src/agent.ts`\n\n. It defines two local tools (weather and current time) and wires them into an `LlmAgent`\n\nrunning on **Gemini 2.5 Flash**.\n\nTool parameters are declared with [Zod](https://zod.dev) schemas, so the ADK derives the function-calling declarations directly from the types:\n\n``` js\nimport {FunctionTool, LlmAgent} from '@google/adk';\nimport {z} from 'zod';\n\nconst cityParameters = z.object({\n  city: z.string().min(1).describe('The city to look up.'),\n});\n\nconst weatherTool = new FunctionTool({\n  name: 'get_weather',\n  description: 'Retrieves the current weather report for a specified city.',\n  parameters: cityParameters,\n  execute: ({city}) => getWeather(city),\n});\n\nexport const rootAgent = new LlmAgent({\n  name: 'weather_time_agent',\n  model: 'gemini-2.5-flash',\n  description: 'Answers questions about the time and weather in a city.',\n  instruction:\n    'You are a helpful assistant. Use the available tools to answer ' +\n    'questions about time and weather. Clearly explain when a city is ' +\n    'unsupported.',\n  tools: [weatherTool, currentTimeTool],\n});\n```\n\nThe tools return a discriminated union — a `success`\n\nresult with a report, or an `error`\n\nresult with a message — which gives the model a consistent shape to reason about:\n\n```\nexport type ToolResult =\n  | {status: 'success'; report: string}\n  | {status: 'error'; errorMessage: string};\n```\n\nWeather and local time are available for New York; other cities return a clear unsupported-city result.\n\nUnlike earlier Go and Python versions of this sample, the TypeScript project ships with a unit test suite built on the Node.js native test runner. A single command type-checks the project and runs the tests:\n\n```\nnpm run check\n```\n\nExample test output:\n\n```\n> adk-hello-world-typescript@1.0.0 build\n> tsc --noEmit\n\n> adk-hello-world-typescript@1.0.0 test\n> tsx --test test/**/*.test.ts\n\n▶ weather and time agent\n  ✔ exports the ADK root agent (0.43ms)\n  ✔ returns the configured New York weather (0.16ms)\n  ✔ rejects unsupported cities (0.45ms)\n  ✔ formats New York time deterministically (12.27ms)\n✔ weather and time agent (14.06ms)\nℹ tests 4\nℹ pass 4\nℹ fail 0\n```\n\nBecause the tools are plain exported functions, they can be tested deterministically without calling the model at all.\n\nThe agent can be debugged locally from the terminal. Use `cli.sh`\n\nor run the npm script directly:\n\n```\nnpm start # runs: adk run src/agent.ts\n```\n\nThe ADK CLI can also be called directly:\n\n```\nnpx adk run src/agent.ts\n```\n\nSample interaction with the agent:\n\n``` php\nUser -> what can you do?\n\nAgent -> I can answer questions about the time and weather in a city using my\ntools. Currently I support New York — for other cities I will let you know\nthat information is not available.\n\nUser -> what is the weather in New York?\n\nAgent -> The weather in New York is sunny with a temperature of 25 degrees\nCelsius (77 degrees Fahrenheit).\n```\n\nThe agent can be debugged from the web GUI running in the local development environment:\n\n```\nnpm run web # runs: adk web\n```\n\nIf developing on a remote VM or container and needing the UI reachable from outside, bind the server to all interfaces:\n\n```\nnpx adk web --host=0.0.0.0\n```\n\nThe UI is the same development interface presented for Python, Java, and Go ADK agents — select `agent`\n\nfrom the dropdown and chat with full tool-calling tracing.\n\nExpose the agent as a plain HTTP API without the UI:\n\n```\nnpx adk api_server\n```\n\nFor deployment options, check the official documentation:\n\nThe TypeScript ADK CLI has deployment built right in. The `cloudrun.sh`\n\nscript loads `.env`\n\nand calls the deploy command:\n\n```\nnpx adk deploy cloud_run \\\n  --project \"$GOOGLE_CLOUD_PROJECT\" \\\n  --region \"$GOOGLE_CLOUD_LOCATION\" \\\n  --service_name \"$SERVICE_NAME\" \\\n  --with_ui true \\\n  src/agent.ts\n```\n\nThe `--with_ui true`\n\nflag bundles the development UI into the deployed Cloud Run service.\n\nOnce deployed, validate your Cloud Run service from the Google Cloud Console, or fetch the service URL from the CLI:\n\n```\ngcloud run services describe hello-world-agent-service \\\n  --region us-central1 --format 'value(status.url)'\n```\n\nThe TypeScript Agent Development Kit (ADK) enables fast agent development using standard TypeScript and Node.js features:\n\n`node:test`\n\n).`adk web`\n\n).`adk deploy cloud_run`\n\n).", "url": "https://wpnews.pro/news/building-ai-agents-with-the-typescript-agent-development-kit-adk", "canonical_source": "https://dev.to/gde/building-ai-agents-with-the-typescript-agent-development-kit-adk-3mf", "published_at": "2026-07-27 17:09:33+00:00", "updated_at": "2026-07-27 17:32:36.448359+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "artificial-intelligence", "large-language-models"], "entities": ["Google", "Agent Development Kit", "TypeScript", "Node.js", "Gemini", "npm", "Microsoft"], "alternates": {"html": "https://wpnews.pro/news/building-ai-agents-with-the-typescript-agent-development-kit-adk", "markdown": "https://wpnews.pro/news/building-ai-agents-with-the-typescript-agent-development-kit-adk.md", "text": "https://wpnews.pro/news/building-ai-agents-with-the-typescript-agent-development-kit-adk.txt", "jsonld": "https://wpnews.pro/news/building-ai-agents-with-the-typescript-agent-development-kit-adk.jsonld"}}