github.com\/juustesout\/javascript-agents-example<\/a> (the TypeScript port lives in the same repo as the JS version).<\/p>\n\n\n\n
\n\n\n\n1. Installation<\/h2>\n\n\n\n
You need Node.js 18+<\/strong> (for the global fetch<\/code>) and an OpenAI API key. Two dev dependencies:<\/p>\n\n\n\ngit clone https:\/\/github.com\/juustesout\/javascript-agents-example.git\ncd javascript-agents-example\nnpm install\ncp .env.example .env\n<\/code><\/pre>\n\n\n\nOpen .env<\/code> and add your key:<\/p>\n\n\n\nOPENAI_API_KEY=sk-proj-your-key-here\nOPENAI_MODEL=gpt-4o-mini\nAGENT_VERBOSE=1\n<\/code><\/pre>\n\n\n\nThe .gitignore<\/code> already has **\/.env<\/code>. The agent loads it automatically via its own built-in loadEnv()<\/code> function. Now compile and run:<\/p>\n\n\n\nnpm run build # tsc \u2014 compiles .ts to dist\/\nnpm run demo # build + run the demo\nnpm run game # build + run the negotiation game\n<\/code><\/pre>\n\n\n\nOnly two dev dependencies: typescript<\/code> and @types\/node<\/code>. That is all the setup there is.<\/p>\n\n\n\n
\n\n\n\n2. Project Structure<\/h2>\n\n\n\nnode-agents-examples-ts\/\n\u251c\u2500\u2500 01_mini_agent\/\n\u2502 \u251c\u2500\u2500 agent.ts # The core loop + 3 tools, fully typed\n\u2502 \u251c\u2500\u2500 demo.ts # Entry point with example prompts\n\u2502 \u2514\u2500\u2500 sample.txt # A test file for the file reader tool\n\u251c\u2500\u2500 02_agent_vs_agent\/\n\u2502 \u2514\u2500\u2500 game.ts # Two agents negotiate a $100 split\n\u251c\u2500\u2500 dist\/ # Compiled output (tsc writes here)\n\u251c\u2500\u2500 tsconfig.json # ES2022, NodeNext module resolution\n\u2514\u2500\u2500 package.json\n<\/code><\/pre>\n\n\n\nSame structure as the JavaScript version, but every file is typed. The tsconfig.json<\/code> targets ES2022 with NodeNext module resolution, so import<\/code> statements compile to .js<\/code> extensions that Node can run directly.<\/p>\n\n\n\n
\n\n\n\n3. The Core Loop \u2014 How Every Agent Works<\/h2>\n\n\n\n
Here is the whole trick in four steps:<\/p>\n\n\n\n
\n- The model receives the full conversation history<\/strong> plus a list of tool schemas<\/strong> (name, description, expected JSON arguments).<\/li>\n\n\n\n
- The model replies with either plain text<\/strong> (it is ready to answer) or one or more tool calls<\/strong> (JSON like
{\"name\": \"calculator\", \"arguments\": {\"expression\": \"2+2\"}}<\/code>).<\/li>\n\n\n\n- If it is a tool call, you<\/strong> run the matching function and append the result as a
role=\"tool\"<\/code> message. Not a framework \u2014 your code.<\/li>\n\n\n\n- Repeat from step 1 until the model returns plain text. That text is the final answer.<\/li>\n<\/ol>\n\n\n\n
The whole loop: model \u2192 tool \u2192 result \u2192 model \u2192 \u2026 \u2192 answer<\/strong>.<\/p>\n\n\n\nTypeScript types \u2014 the safety net<\/h3>\n\n\n\n
The first thing you notice in the TypeScript version is the type definitions. Every message, every tool call, every response shape is explicitly typed:<\/p>\n\n\n\n
export type ToolCall = {\n id: string;\n type: \"function\";\n function: {\n name: string;\n arguments: string;\n };\n};\n\nexport type ChatMessage = {\n role: \"system\" | \"user\" | \"assistant\" | \"tool\";\n content: string | null;\n tool_call_id?: string;\n tool_calls?: ToolCall[];\n};\n\nexport type ModelReply = {\n content: string | null;\n tool_calls?: ToolCall[];\n};\n<\/code><\/pre>\n\n\n\nThese types are not decorative \u2014 they are the contract between your code and the OpenAI API. If you accidentally set role: \"system\"<\/code> on a tool result, the TypeScript compiler flags it immediately. The ModelReply<\/code> type tells you exactly what shape the API response should have, so you never have to guess.<\/p>\n\n\n\nThe MiniAgent class<\/h3>\n\n\n\nexport class MiniAgent {\n systemPrompt: string;\n model: string;\n temperature: number;\n maxToolIters: number;\n verbose: boolean;\n baseUrl: string;\n apiKey?: string;\n tools: Record<string, Tool>;\n messages: ChatMessage[];\n\n constructor(\n systemPrompt: string,\n {\n model = null,\n temperature = 0.7,\n maxToolIters = DEFAULT_MAX_TOOL_ITERS,\n verbose = DEFAULT_VERBOSE,\n baseUrl = process.env.OPENAI_BASE_URL || \"https:\/\/api.openai.com\/v1\",\n apiKey = process.env.OPENAI_API_KEY,\n }: {\n model?: string | null;\n temperature?: number;\n maxToolIters?: number;\n verbose?: boolean;\n baseUrl?: string;\n apiKey?: string;\n } = {},\n ) {\n this.systemPrompt = systemPrompt;\n this.model = model || DEFAULT_MODEL;\n this.temperature = temperature;\n this.maxToolIters = maxToolIters;\n this.verbose = verbose;\n this.baseUrl = baseUrl.replace(\/\\\/+$\/, \"\");\n this.apiKey = apiKey;\n this.tools = {};\n this.messages = [];\n }\n}\n<\/code><\/pre>\n\n\n\nThe constructor takes a destructured options object \u2014 every parameter is optional and has a default. The messages<\/code> array is typed as ChatMessage[]<\/code>, so adding a message with the wrong structure is a compile-time error, not a runtime surprise.<\/p>\n\n\n\nThe run()<\/code> method \u2014 the heart<\/h3>\n\n\n\nasync run(userPrompt: string, { reset = true }: { reset?: boolean } = {}): Promise<string> {\n if (reset || this.messages.length === 0) {\n this.messages = [\n { role: \"system\", content: this.systemPrompt },\n { role: \"user\", content: userPrompt },\n ];\n } else {\n this.messages.push({ role: \"user\", content: userPrompt });\n }\n\n for (let iteration = 1; iteration <= this.maxToolIters; iteration++) {\n this._log(`iteration ${iteration}: calling the model...`, _DIM);\n const reply = await this._callModel();\n\n if (reply.tool_calls && reply.tool_calls.length > 0) {\n await this._handleToolCalls(reply.tool_calls);\n continue; \/\/ loop back to the model\n }\n\n const answer = reply.content || \"\";\n this.messages.push({ role: \"assistant\", content: answer });\n this._log(\"final answer received.\", _DIM);\n return answer;\n }\n\n throw new Error(`No answer after ${this.maxToolIters} iterations.`);\n}\n<\/code><\/pre>\n\n\n\nThe TypeScript return type Promise<string><\/code> tells the caller exactly what to expect. No surprises.<\/p>\n\n\n\nHow _callModel()<\/code> works<\/h3>\n\n\n\nThis is the only network call in the whole project. It converts the tool registry into OpenAI’s JSON schema format and sends the conversation alongside it:<\/p>\n\n\n\n
async _callModel(): Promise<ModelReply> {\n const toolSchemas = Object.values(this.tools).map((tool) => tool.toOpenAISchema());\n\n const response = await fetch(`${this.baseUrl}\/chat\/completions`, {\n method: \"POST\",\n headers: {\n \"Content-Type\": \"application\/json\",\n Authorization: `Bearer ${this.apiKey}`,\n },\n body: JSON.stringify({\n model: this.model,\n messages: this.messages,\n temperature: this.temperature,\n tools: toolSchemas.length ? toolSchemas : undefined,\n tool_choice: toolSchemas.length ? \"auto\" : undefined,\n }),\n });\n\n if (!response.ok) {\n const text = await response.text();\n throw new Error(`OpenAI API error ${response.status}: ${text}`);\n }\n\n const data = await response.json();\n return data.choices[0].message as ModelReply;\n}\n<\/code><\/pre>\n\n\n\nThe return type assertion as ModelReply<\/code> tells the compiler what shape the API response has \u2014 the rest of the code is fully typed from this point on.<\/p>\n\n\n\nHow tool results get back into context<\/h3>\n\n\n\nasync _handleToolCalls(toolCalls: ToolCall[]): Promise<void> {\n this.messages.push({\n role: \"assistant\",\n content: null,\n tool_calls: toolCalls.map((call) => ({\n id: call.id,\n type: \"function\",\n function: {\n name: call.function.name,\n arguments: call.function.arguments,\n },\n })),\n });\n\n for (const call of toolCalls) {\n const result = await this._executeTool(call.function.name, call.function.arguments);\n this.messages.push({ role: \"tool\", tool_call_id: call.id, content: result });\n }\n}\n<\/code><\/pre>\n\n\n\nEvery tool_call_id<\/code> must pair back to the matching call. The TypeScript compiler enforces that tool_call_id<\/code> is a string, preventing a whole class of bugs.<\/p>\n\n\n\nExecuting a tool<\/h3>\n\n\n\nasync _executeTool(name: string, argumentsJson: string): Promise<string> {\n const tool = this.tools[name];\n if (!tool) return `Error: unknown tool '${name}'.`;\n\n try {\n const args = JSON.parse(argumentsJson);\n if (typeof args !== \"object\" || args === null || Array.isArray(args)) {\n throw new TypeError(\"tool arguments must be a JSON object\");\n }\n this._log(` -> ${name}(${JSON.stringify(args)})`, _YELLOW);\n result = String(await tool.func(args as Record<string, unknown>));\n } catch (exc) {\n result = `Error calling '${name}': ${exc instanceof Error ? exc.message : String(exc)}`;\n }\n\n this._log(` <- result: ${JSON.stringify(String(result).slice(0, 120))}`, _MAGENTA);\n return String(result);\n}\n<\/code><\/pre>\n\n\n\nThe as Record<string, unknown><\/code> cast tells TypeScript that the parsed JSON object is safe to pass to the tool function \u2014 the actual validation happens at runtime in the function itself.<\/p>\n\n\n\n
\n\n\n\n4. Tools \u2014 Plain Functions, Typed Schemas<\/h2>\n\n\n\n
A tool in this system is a class with a name, description, JSON Schema and a function:<\/p>\n\n\n\n
class Tool {\n name: string;\n description: string;\n parameters: ToolParameters;\n func: (args: Record<string, unknown>) => string | Promise<string>;\n\n toOpenAISchema() {\n return {\n type: \"function\",\n function: {\n name: this.name,\n description: this.description,\n parameters: this.parameters,\n },\n };\n }\n}\n<\/code><\/pre>\n\n\n\nThe ToolParameters<\/code> type is the JSON Schema shape:<\/p>\n\n\n\nexport type ToolParameters = {\n type: \"object\";\n properties: Record<string, Record<string, unknown>>;\n required?: string[];\n};\n<\/code><\/pre>\n\n\n\nThree tools ship with the agent, each registered via addTool()<\/code>:<\/p>\n\n\n\naddTool(\n name: string,\n description: string,\n parameters: ToolParameters,\n func: (args: Record<string, unknown>) => string | Promise<string>\n): this { ... }\n<\/code><\/pre>\n\n\n\nTool 1: Calculator \u2014 hand-written recursive descent parser<\/h3>\n\n\n\n
Same parser as the JavaScript version: a recursive descent parser that only accepts arithmetic \u2014 + - * \/ \/\/ % **<\/code>, parentheses, and the constants pi<\/code> and e<\/code>. No eval()<\/code>, no new Function()<\/code>, no arbitrary code execution. Each grammar rule is a function:<\/p>\n\n\n\nexport function calculator(expression: string): string {\n try {\n return String(_parseExpression(expression));\n } catch (exc) {\n return `Error: ${exc instanceof Error ? exc.message : String(exc)}`;\n }\n}\n<\/code><\/pre>\n\n\n\nTool 2: Safe file reader (path traversal defence)<\/h3>\n\n\n\n
Uses path.relative()<\/code> to block any attempt to escape the allowed directory:<\/p>\n\n\n\nexport function read_local_file(filepath: string): string {\n try {\n const base = resolve(_DEFAULT_BASE_DIR);\n const target = resolve(base, String(filepath));\n const rel = relative(base, target);\n if (rel.startsWith(\"..\") || isAbsolute(rel)) {\n return `Error: '${filepath}' escapes the allowed directory. Path traversal blocked.`;\n }\n if (!existsSync(target)) return `Error: file not found.`;\n const stat = statSync(target);\n if (stat.size > _MAX_FILE_BYTES) return `Error: file too large.`;\n return readFileSync(target, \"utf8\").replace(\/\\s+$\/, \"\");\n } catch (exc) {\n return `Error reading file: ${exc instanceof Error ? exc.message : String(exc)}`;\n }\n}\n<\/code><\/pre>\n\n\n\nTool 3: Web search (zero API key, DuckDuckGo scraping)<\/h3>\n\n\n\n
Scrapes the public DuckDuckGo HTML endpoint with fetch<\/code> and regex \u2014 zero dependencies, zero API keys:<\/p>\n\n\n\nexport async function web_search(query: string, max_results = 5): Promise<string> {\n const res = await fetch(\n `https:\/\/html.duckduckgo.com\/html\/?q=${encodeURIComponent(query)}`,\n { headers: { \"User-Agent\": \"...\" },\n signal: AbortSignal.timeout(15_000) }\n );\n const html = await res.text();\n const anchors = [...html.matchAll(\/class=\"result__a\" ... \/gs)];\n const snippets = [...html.matchAll(\/class=\"result__snippet\" ... \/gs)];\n \/\/ Build formatted results\n return lines.join(\"\\n\\n\");\n}\n<\/code><\/pre>\n\n\n\nRegistering tools<\/h3>\n\n\n\n
Tools are registered via chained addTool()<\/code> calls, wrapping each function to extract the named argument from the args<\/code> object:<\/p>\n\n\n\nexport function registerBuiltinTools(agent: MiniAgent): MiniAgent {\n agent\n .addTool(\"calculator\", \"Evaluate a math expression...\",\n { type: \"object\", properties: {\n expression: { type: \"string\", description: \"...\" },\n }, required: [\"expression\"] },\n (args) => calculator(String(args.expression))\n )\n .addTool(\"read_local_file\", \"Read a text file...\",\n { type: \"object\", properties: {\n filepath: { type: \"string\", description: \"...\" },\n }, required: [\"filepath\"] },\n (args) => read_local_file(String(args.filepath))\n )\n .addTool(\"web_search\", \"Search the web...\",\n { type: \"object\", properties: {\n query: { type: \"string\", description: \"...\" },\n max_results: { type: \"integer\", description: \"...\" },\n }, required: [\"query\"] },\n (args) => web_search(String(args.query), Number(args.max_results ?? 5))\n );\n return agent;\n}\n<\/code><\/pre>\n\n\n\n
\n\n\n\n