@narimangardi/agent-loop 0.1.0 → 0.3.0

package/README.md

@@ -1,5 +1,9 @@
 # agent-loop
 
+[![Tests](https://github.com/NarimanGardi/agent-loop/actions/workflows/tests.yml/badge.svg)](https://github.com/NarimanGardi/agent-loop/actions/workflows/tests.yml)
+[![npm version](https://img.shields.io/npm/v/@narimangardi/agent-loop)](https://www.npmjs.com/package/@narimangardi/agent-loop)
+[![License](https://img.shields.io/npm/l/@narimangardi/agent-loop)](LICENSE)
+
 A tiny, zero-dependency, provider-agnostic **agent tool-loop** for TypeScript.
 The whole thing is one small class: ask an LLM, run the tools it asks for, feed
 the results back, repeat until it answers. Bring your own model.
@@ -51,12 +55,28 @@ console.log(result.steps);  // how many round-trips it took
 
 1. Send the conversation + tool specs to the provider.
 2. If the provider returns a **message**, that's the answer — return it.
-3. If it returns **tool calls**, run each tool and append the results.
+3. If it returns **tool calls**, run them (concurrently within a turn) and append the results.
 4. Go back to step 1 (up to `maxSteps`, default 10).
 
 Unknown tools and thrown errors are handed back to the model as text, so it can
 recover instead of crashing the loop.
 
+## Observe the loop
+
+Pass optional hooks to watch it run — for logging, a progress UI, or tracing:
+
+```ts
+const agent = new Agent({
+  provider,
+  tools: [getWeather],
+  onStep: (n) => console.log(`step ${n}`),
+  onToolCall: (call) => console.log(`→ ${call.name}`, call.arguments),
+  onToolResult: (call, output) => console.log(`← ${call.name}: ${output}`),
+});
+```
+
+Hooks may be async — the loop awaits them.
+
 ## Plug in a model
 
 There's one interface to implement — map your LLM's tool-calling API to a
@@ -102,6 +122,11 @@ const openai: Provider = {
 The same shape works for Anthropic, Gemini, Ollama, or anything else — it's just
 "messages + tools in, message-or-tool-calls out."
 
+Complete, typechecked adapters are in [`examples/openai.ts`](examples/openai.ts)
+and [`examples/anthropic.ts`](examples/anthropic.ts) — the same interface mapped
+onto two very different APIs — plus a runnable
+[`examples/weather-agent.ts`](examples/weather-agent.ts).
+
 ## Limitations
 
 Deliberately small. Worth knowing:

package/dist/index.cjs

@@ -43,6 +43,9 @@ var Agent = class {
   toolSpecs;
   system;
   maxSteps;
+  onStep;
+  onToolCall;
+  onToolResult;
   constructor(options) {
     const tools = options.tools ?? [];
     this.provider = options.provider;
@@ -50,25 +53,31 @@ var Agent = class {
     this.toolSpecs = tools.map(({ name, description, parameters }) => ({ name, description, parameters }));
     this.system = options.system;
     this.maxSteps = options.maxSteps ?? 10;
+    this.onStep = options.onStep;
+    this.onToolCall = options.onToolCall;
+    this.onToolResult = options.onToolResult;
   }
   async run(prompt) {
     const messages = [];
     if (this.system !== void 0) messages.push({ role: "system", content: this.system });
     messages.push({ role: "user", content: prompt });
     for (let step = 1; step <= this.maxSteps; step++) {
+      await this.onStep?.(step);
       const response = await this.provider.complete({ messages, tools: this.toolSpecs });
       if (response.kind === "message") {
         messages.push({ role: "assistant", content: response.content });
         return { text: response.content, steps: step, messages };
       }
       messages.push({ role: "assistant", content: null, toolCalls: response.toolCalls });
-      for (const call of response.toolCalls) {
-        messages.push({
-          role: "tool",
-          toolCallId: call.id,
-          name: call.name,
-          content: await this.runTool(call)
-        });
+      const results = await Promise.all(
+        response.toolCalls.map(async (call) => {
+          await this.onToolCall?.(call);
+          return { call, output: await this.runTool(call) };
+        })
+      );
+      for (const { call, output } of results) {
+        await this.onToolResult?.(call, output);
+        messages.push({ role: "tool", toolCallId: call.id, name: call.name, content: output });
       }
     }
     throw new MaxStepsExceededError(this.maxSteps, messages);

package/dist/index.d.cts

@@ -61,6 +61,12 @@ interface AgentOptions {
     system?: string;
     /** Max provider round-trips before giving up. Default 10. */
     maxSteps?: number;
+    /** Called before each provider round-trip (1-indexed). */
+    onStep?: (step: number) => void | Promise<void>;
+    /** Called when the model requests a tool, before it runs. */
+    onToolCall?: (call: ToolCall) => void | Promise<void>;
+    /** Called after a tool runs, with its output (or error text). */
+    onToolResult?: (call: ToolCall, output: string) => void | Promise<void>;
 }
 interface AgentResult {
     /** The assistant's final text answer. */
@@ -77,7 +83,8 @@ declare class MaxStepsExceededError extends Error {
 }
 /**
  * The whole agent: ask the provider, run any tools it calls, feed the results
- * back, repeat until it returns a final answer (or maxSteps is hit).
+ * back, repeat until it returns a final answer (or maxSteps is hit). Pass the
+ * optional hooks to watch each step go by.
  */
 declare class Agent {
     private readonly provider;
@@ -85,6 +92,9 @@ declare class Agent {
     private readonly toolSpecs;
     private readonly system?;
     private readonly maxSteps;
+    private readonly onStep?;
+    private readonly onToolCall?;
+    private readonly onToolResult?;
     constructor(options: AgentOptions);
     run(prompt: string): Promise<AgentResult>;
     /** Run one tool. Unknown tools and thrown errors come back as text the model can recover from. */

package/dist/index.d.ts

@@ -61,6 +61,12 @@ interface AgentOptions {
     system?: string;
     /** Max provider round-trips before giving up. Default 10. */
     maxSteps?: number;
+    /** Called before each provider round-trip (1-indexed). */
+    onStep?: (step: number) => void | Promise<void>;
+    /** Called when the model requests a tool, before it runs. */
+    onToolCall?: (call: ToolCall) => void | Promise<void>;
+    /** Called after a tool runs, with its output (or error text). */
+    onToolResult?: (call: ToolCall, output: string) => void | Promise<void>;
 }
 interface AgentResult {
     /** The assistant's final text answer. */
@@ -77,7 +83,8 @@ declare class MaxStepsExceededError extends Error {
 }
 /**
  * The whole agent: ask the provider, run any tools it calls, feed the results
- * back, repeat until it returns a final answer (or maxSteps is hit).
+ * back, repeat until it returns a final answer (or maxSteps is hit). Pass the
+ * optional hooks to watch each step go by.
  */
 declare class Agent {
     private readonly provider;
@@ -85,6 +92,9 @@ declare class Agent {
     private readonly toolSpecs;
     private readonly system?;
     private readonly maxSteps;
+    private readonly onStep?;
+    private readonly onToolCall?;
+    private readonly onToolResult?;
     constructor(options: AgentOptions);
     run(prompt: string): Promise<AgentResult>;
     /** Run one tool. Unknown tools and thrown errors come back as text the model can recover from. */

package/dist/index.js

@@ -15,6 +15,9 @@ var Agent = class {
   toolSpecs;
   system;
   maxSteps;
+  onStep;
+  onToolCall;
+  onToolResult;
   constructor(options) {
     const tools = options.tools ?? [];
     this.provider = options.provider;
@@ -22,25 +25,31 @@ var Agent = class {
     this.toolSpecs = tools.map(({ name, description, parameters }) => ({ name, description, parameters }));
     this.system = options.system;
     this.maxSteps = options.maxSteps ?? 10;
+    this.onStep = options.onStep;
+    this.onToolCall = options.onToolCall;
+    this.onToolResult = options.onToolResult;
   }
   async run(prompt) {
     const messages = [];
     if (this.system !== void 0) messages.push({ role: "system", content: this.system });
     messages.push({ role: "user", content: prompt });
     for (let step = 1; step <= this.maxSteps; step++) {
+      await this.onStep?.(step);
       const response = await this.provider.complete({ messages, tools: this.toolSpecs });
       if (response.kind === "message") {
         messages.push({ role: "assistant", content: response.content });
         return { text: response.content, steps: step, messages };
       }
       messages.push({ role: "assistant", content: null, toolCalls: response.toolCalls });
-      for (const call of response.toolCalls) {
-        messages.push({
-          role: "tool",
-          toolCallId: call.id,
-          name: call.name,
-          content: await this.runTool(call)
-        });
+      const results = await Promise.all(
+        response.toolCalls.map(async (call) => {
+          await this.onToolCall?.(call);
+          return { call, output: await this.runTool(call) };
+        })
+      );
+      for (const { call, output } of results) {
+        await this.onToolResult?.(call, output);
+        messages.push({ role: "tool", toolCallId: call.id, name: call.name, content: output });
       }
     }
     throw new MaxStepsExceededError(this.maxSteps, messages);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@narimangardi/agent-loop",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "A tiny, zero-dependency, provider-agnostic agent tool-loop for TypeScript. Build your own AI agent in ~100 lines.",
   "keywords": ["ai", "agent", "tool-use", "function-calling", "llm", "typescript"],
   "license": "MIT",
@@ -24,9 +24,11 @@
     "build": "tsup src/index.ts --format esm,cjs --dts --clean",
     "test": "vitest run",
     "typecheck": "tsc --noEmit",
+    "typecheck:examples": "tsc -p tsconfig.examples.json",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "tsup": "^8.0.0",
     "typescript": "^5.6.0",
     "vitest": "^3.0.0"