@alex-ai/agent

Part of the alex-ai ecosystem, @alex-ai/agent provides a powerful, composable agent framework for building AI-powered assistants that can reason, use tools, and interact with users or other agents. It is designed to be modular, extensible, and easy to integrate with various language models and toolchains.

Features

• Composable Agents: Create agents that can use tools, call sub-agents, or delegate tasks to fallback agents.
• Tool Integration: Define tools with input/output schemas using Zod. Tools can be synchronous or stream results as agent messages.
• Model Agnostic: Works with multiple LLM providers (OpenAI, Anthropic, Google Gemini, DeepSeek, Ollama) via the ai SDK.
• Memory & Context: Agents maintain memory and conversation history for contextual reasoning.
• Streaming Support: Stream agent responses and tool results in real time.
• Error Handling & Recovery: Built-in mechanisms for handling tool call failures and invalid arguments.

Installation

npm install @alex-ai/agent

Basic Usage

import { Agent } from "@alex-ai/agent";
import { z } from "zod";
import { openai } from "ai";

const echoTool = {
  name: "echo",
  description: "Echoes back the input",
  inputSchema: z.object({ text: z.string() }),
  execute: async ({ text }) => ({ echoedText: text }),
};

const agent = new Agent({
  name: "EchoAgent",
  description: "An agent that echoes your input.",
  model: openai("gpt-3.5-turbo"),
  tools: [echoTool],
});

for await (const chunk of agent.runStream({ prompt: "Say hello!" })) {
  // Handle streaming output here
}

Concepts

Agents

An Agent encapsulates:

• A language model (LLM)
• A set of available tools (functions)
• Optional sub-agents or fallback agents
• Memory/state management

Tools

Tools are functions described by:

• Name & description
• Input/output schemas (Zod)
• An execute function (sync/async/generator)

You can define standard tools or streaming tools (which yield message chunks).

Sub-agents & Fallbacks

Agents can delegate tasks to other agents ("sub-agents") or fall back to another agent if they get stuck.

Streaming API

The .runStream() method yields structured chunks representing messages, tool calls/results, summaries, and token usage.

FunctionTool

A tool definition object. See source/types for full type signature.

Example Tool Definition

import { z } from "zod";

const addNumbers = {
  name: "addNumbers",
  description: "Adds two numbers together.",
  inputSchema: z.object({
    a: z.number(),
    b: z.number(),
  }),
  execute: async ({ a, b }) => ({ result: a + b }),
};

For more details and advanced usage patterns, see the alex-ai ecosystem documentation.