Write your first AI Agent with Typescript

SWAN — Thu, 16 Apr 2026 14:43:15 +0000

Let’s create a simple Math AI Agent. Instead of talking about AI agents in theory, let’s jump straight into building one. No complex setup. No overwhelming abstractions. Just a clean, practical introduction to building your first intelligent agent with the SWAN Framework.

PROJECT SETUP

Create an empty Typescript project directory and install dependencies:

npm install --save-dev typescript @types/node
npm install @ssww.one/framework zod

Create tsconfig.json file

{
  "compilerOptions": {
    "outDir": "./dist",
    "module": "nodenext",
    "target": "esnext",
    "lib": ["esnext"],
    "types": ["node"],
    "sourceMap": true,
    "declaration": true,
    "declarationMap": true,
    "strict": true,
    "jsx": "react-jsx",
    "isolatedModules": true,
    "noUncheckedSideEffectImports": true,
    "moduleDetection": "force",
    "skipLibCheck": true,
  }
}

Create an empty index.ts file

.
├── index.ts
├── node_modules
├── package.json
├── package-lock.json
└── tsconfig.json

Update your package.json scripts to automatically transpile ts files to js and execute node index.js

{
  ...
  "scripts": {
    "start": "rm -rf dist && tsc && node dist"
  },
  ...
}

WRITE AI-AGENTS

Start with a typical Agents simple blueprint on index.ts

import { AgentTool, OpenAILLM, startAgentCLI, loop } from "@ssww.one/framework";

export async function agent(at: AgentTool) {
  at.print('Hello there, may I help you?', true); // GREETINGS

  await loop(async () => {
    const instruction: string = await at.waitForUserInstruction();
    const response: string = await at.askLLM(`Reply to: ${instruction}`);
    at.print(response, true); // true on 2nd param to close response
  });
}

startAgentCLI(agent, {
  llm: new OpenAILLM()
});

Code above is a simple agent that prints greetings in the first execution, after that it will loop forever to wait for user prompt and then ask AI for an answer and print the response to the user.

When you run npm start, it will run the agent function, print greetings, ask for prompt

$ npm start

> project@1.0.0 start
> rm -rf dist && tsc && node dist

◇ injected env (0) from .env // tip: ⌘ multiple files { path: ['.env.local', '.env'] }
◇ injected env (0) from .env // tip: ⌁ auth for agents [www.vestauth.com]
Hello there, may I help you?
? prompt ‣

if you respond to the prompt it will show an error, since you havent configure any API Key and Open AI LLM model.

Add OpenAI LLM API key and model name

Create a new file .env and then put your API key and model name like this:

CHATGPT_APIKEY="sk-proj-rWWdZnm3f...."
CHATGPT_MODEL="gpt-4.1"

Now your project directory files become:

.
├── .env
├── index.ts
├── node_modules
├── package.json
├── package-lock.json
└── tsconfig.json

Try run npm start again, and now it should work well

$ npm start

> project@1.0.0 start
> rm -rf dist && tsc && node dist

◇ injected env (0) from .env // tip: ⌘ enable debugging { debug: true }
◇ injected env (0) from .env // tip: ⌁ auth for agents [www.vestauth.com]
Hello there, may I help you?
✔ prompt · Hi, how are you?
Loading...
Reply to: Hi, how are you?
"I'm good, thank you! How are you?"
? prompt ‣

Lets back to the Math AI Agent.

Change your index.ts to this simple Math AI Agent function

import { AgentTool, OpenAILLM, startAgentCLI, loop } from "@ssww.one/framework";
import z from "zod";

export async function agent(at: AgentTool) {
  at.print("🧮 I'm your math agent. Ask me anything!", true);

  await loop(async () => {
    const question = await at.waitForUserInstruction();

    const result = await at.askLLM(
      `Is this a math question: "${question}"?`,
      z.object({ isMath: z.boolean() })
    );

    if (result.isMath) {
      const answer = await at.askLLM(`Solve this clearly: ${question}`);
      at.print(answer, true);
    } else {
      at.print("❌ I only handle math questions!", true);
    }
  });
}
startAgentCLI(agent, {
  llm: new OpenAILLM()
});

These agent works as steps below:

Waits for you to type a question
Checks if your question is related to math
If yes → it solves the problem step-by-step
If no → it politely rejects it

Congratulations, you have successfully created your first AI Agent with Typescript.

BONUS

You can change the LLM with another provider like OpenRouter or Google Gen AI

On provider Open Router or other providers that support OpenAI SDK, you just need to add CHATGPT_ENDPOINT key on .env file

CHATGPT_APIKEY="sk-proj-rWWdZnm3f...."
CHATGPT_MODEL="gpt-4.1"
CHATGPT_ENDPOINT="https://openrouter.ai/api/v1"

On provider Google Gen AI, you need to replace the whole LLM and .env with new values

index.ts

import { GoogleGenAILLM } from "@ssww.one/framework";

// agents function

startAgentCLI(agent, {
  llm: new GoogleGenAILLM()
});

.env

GOOGLE_GENAI_APIKEY="egzz222nufi...."
GOOGLE_GENAI_MODEL="gemini-2.5-flash"

Full documentation visit https://ssww.one/docs

DEV Community: SWAN

Write your first AI Agent with Typescript