agentnode-ts

A lightweight AI agent framework for TypeScript.

Note

agentnode-ts is under active development. APIs and capabilities may change as the framework evolves.

Features

• Multi-turn conversations
• Custom tool calling
• Multiple tool calls in one run
• Streaming responses
• Structured output (JSON schema)
• OpenAI support
• Fully typed TypeScript API

Installation

npm install agentnode-ts

Set your OpenAI API key:

export OPENAI_API_KEY="your-api-key"

Quick Start

import {
  AgentNode,
  OpenAIModel,
} from "agentnode-ts";

const model = new OpenAIModel({
  model: "gpt-4.1-mini",
});

const agent = new AgentNode({
  model,
  instructions: "You are a concise and helpful assistant.",
});

const response = await agent.run(
  "Explain what an AI agent is in one sentence.",
);

console.log(response.text);

Conversations

An agent remembers earlier messages across calls to run():

const firstResponse = await agent.run(
  "My favorite color is blue.",
);
console.log(firstResponse.text);
// Blue is a great choice! Is there something specific you'd like to know or discuss about the color blue?

const secondResponse = await agent.run(
  "What is my favorite color?",
);
console.log(secondResponse.text);
// Your favorite color is blue.

You can also continue from existing history:

const history = agent.getHistory();
const restoredAgent = new AgentNode({
  model,
  instructions: "You are a concise and helpful assistant.",
  history,
});

const restoredResponse = await restoredAgent.run(
  "What fact did I share with you?",
);
console.log(restoredResponse.text);
// You shared that your favorite color is blue.

Use one AgentNode per conversation. Start over with:

agent.reset();

Tools

Define a tool:

import type {
  Tool,
} from "agentnode-ts";

const getCurrentTimeTool: Tool = {
  name: "get_current_time",
  description: "Get the current date and time for an IANA time zone.",
  inputSchema: {
    type: "object",
    properties: {
      timeZone: {
        type: "string",
        description: "An IANA time zone such as America/Los_Angeles.",
      },
    },
    required: ["timeZone"],
    additionalProperties: false,
  },

  async execute(input) {
    const timeZone = input.timeZone;
    if (typeof timeZone !== "string") {
      throw new Error("timeZone must be a string.");
    }

    return {
      currentTime: new Intl.DateTimeFormat(
        "en-US",
        {
          dateStyle: "full",
          timeStyle: "long",
          timeZone,
        },
      ).format(new Date()),
    };
  },
};

Register the tool and run the agent:

const agent = new AgentNode({
  model,
  instructions: "You are a concise and helpful assistant.",
  tools: [getCurrentTimeTool],
});

const response = await agent.run(
  "What time is it in San Francisco?",
);

console.log(response.text);

Examples

From a cloned repository, install dependencies:

npm install

Run the basic example:

npx tsx examples/basic.ts

Run the conversation example:

npx tsx examples/conversation/index.ts

Run the tool-calling example:

npx tsx examples/current-time/index.ts

Run the streaming example:

npx tsx examples/stream-structured/stream.ts

Run the structured output example:

npx tsx examples/stream-structured/structured.ts

Supported Providers

• OpenAI

Streaming

const stream = await agent.runStream("Tell me a short story.");

for await (const chunk of stream) {
  if (chunk.type === "text_delta") {
    process.stdout.write(chunk.delta);
  }
}

Note: Streaming currently returns only the first model response and does not execute tools.

Structured Output

const agent = new AgentNode({
  model,
  instructions: "You are a helpful assistant.",
  responseFormat: {
    type: "json_schema",
    name: "weather",
    jsonSchema: {
      type: "object",
      properties: {
        location: { type: "string" },
        temperature: { type: "number" },
      },
      required: ["location", "temperature"],
      additionalProperties: false,
    },
    strict: true,
  },
});

const response = await agent.run("What's the weather in Paris?");
console.log(response.text); // JSON string matching the schema

Roadmap

• Context window management
• Additional model providers
• Persistent memory
• MCP support
• Multi-step planning

License

MIT