Agention

AI Agents Without the Magic

A comprehensive TypeScript toolkit for building LLM-powered agents with RAG, and multi-agent workflows. No hidden state machines, no forced abstractions—just typed agents, composable graphs, and complete control in a complete toolkit.

Documentation • Examples • GitLab • npm

Quick Start

1. Install

Install only what you need with selective imports:

# Install core library + Claude SDK
npm install @agentionai/agents @anthropic-ai/sdk

2. Get API Key

Get an API key from your chosen provider:

• Claude: console.anthropic.com
• OpenAI: platform.openai.com
• Gemini: aistudio.google.com
• Mistral: console.mistral.ai
• OpenRouter: openrouter.ai/keys — one key, dozens of upstream providers
• Ollama / llama.cpp: no API key needed — run models locally (see Agents guide)

Set it as an environment variable:

export ANTHROPIC_API_KEY=your-key-here

3. Create Your First Agent

// Import only Claude - no other agent SDKs required!
import { ClaudeAgent } from '@agentionai/agents/claude';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'assistant',
  name: 'Assistant',
  description: 'You are a helpful assistant.',
  model: 'claude-sonnet-4-5',
});

const response = await agent.execute('What can you help me with?');
console.log(response);

Selective Imports

Import only the agents you need:

import { ClaudeAgent } from '@agentionai/agents/claude';     // Requires @anthropic-ai/sdk
import { OpenAiAgent } from '@agentionai/agents/openai';     // Requires openai
import { GeminiAgent } from '@agentionai/agents/gemini';     // Requires @google/generative-ai
import { MistralAgent } from '@agentionai/agents/mistral';   // Requires @mistralai/mistralai
import { OpenRouterAgent } from '@agentionai/agents/openrouter'; // Requires @openrouter/sdk
import { OllamaAgent } from '@agentionai/agents/ollama';     // Requires ollama (local, no API key)
import { LlamaCppAgent } from '@agentionai/agents/llamacpp'; // Requires openai (local, no API key)

Or import everything (requires all SDKs):

import { ClaudeAgent, OpenAiAgent } from '@agentionai/agents';

Features

• Multi-Provider, No Lock-in - Claude, OpenAI, Gemini, Mistral, OpenRouter (one key, dozens of upstream providers), plus local models via Ollama and llama.cpp—same interface. Switch models with one line. listModels() asks any provider what it currently offers, in one shared shape.
• Composable Context Management - Tool result masking (lossless, free) + rolling summarization (auto-firing) + sub-agent delegation (token isolation by architecture).
• Streaming - executeStream() on Claude, OpenAI, OpenRouter, and all OpenAI-compatible agents. Yields { type: "text" | "reasoning" } chunks; tool calls handled transparently.
• Built-In Tools - Use provider-defined server-side tools (e.g. Anthropic's web search, bash, text editor) alongside your own.
• Composable, Not Magical - Agents are objects. Pipelines are arrays. No hidden state, no surprises.
• Multimodal / Vision - Send images alongside text with a unified MessageContent[] API across all providers.
• Full Observability - Per-call token counts, execution timing, pipeline structure visualization.
• TypeScript-Native - Strict typing, interfaces, and generics from the ground up.
• RAG Ready - LanceDB vector store, token-aware chunking, ingestion pipeline out of the box.

Agent with Tools

import { GeminiAgent, Tool } from '@agentionai/agents/gemini';

const weatherTool = new Tool({
  name: 'get_weather',
  description: 'Get the current weather for a location',
  inputSchema: {
    type: 'object',
    properties: {
      location: { type: 'string', description: 'City name' },
    },
    required: ['location'],
  },
  execute: async ({ location }) => {
    // In production, call a weather API
    return JSON.stringify({
      location,
      temperature: 22,
      conditions: 'Sunny',
    });
  },
});

const agent = new GeminiAgent({
  apiKey: process.env.GEMINI_API_KEY,
  id: 'weather-agent',
  name: 'Weather Agent',
  description: 'You are a weather assistant.',
  model: 'gemini-flash-lite-latest',
  tools: [weatherTool],
});

const response = await agent.execute("What's the weather in Paris?");

Context Management

Every agent conversation grows — tool results pile up, turns accumulate, tokens compound. Agention's history plugins keep the context window lean automatically, without manual bookkeeping.

import { toolResultMaskingPlugin, compressionPlugin } from '@agentionai/agents/history/plugins';
import { History } from '@agentionai/agents/history';

// Mask old tool results at read time — sync, free, lossless
const maskingPlugin = toolResultMaskingPlugin({ keepRecentResults: 2 });

// Compress old turns into a rolling summary — auto-fires past a token budget
const history = new History([], { maxTokens: 50000 })
  .use(maskingPlugin)
  .use(compressionPlugin(summaryAgent, { autoReduceWhen: { maxTokens: 8000 } }));

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'researcher',
  name: 'Researcher',
  description: 'Research topics thoroughly.',
  model: 'claude-sonnet-4-6',
  tools: [searchTool, maskingPlugin.retrieveTool],
}, history);

Context Management guide → · History API →

Local Models (Ollama / llama.cpp / OpenAI-compatible servers)

Run models on your own machine — no API key required. Same agent interface as every other provider:

import { OllamaAgent } from '@agentionai/agents/ollama';
import { LlamaCppAgent } from '@agentionai/agents/llamacpp';

// Ollama (https://ollama.com) — pull a model first: `ollama pull qwen2.5`
const ollama = new OllamaAgent({
  id: 'local-ollama',
  name: 'Local Assistant',
  description: 'You are a helpful assistant.',
  model: 'qwen2.5',
  apiKey: '',
});

// llama.cpp server (`llama-server -m model.gguf`) — OpenAI-compatible API
const llamaCpp = new LlamaCppAgent({
  id: 'local-llamacpp',
  name: 'Local Assistant',
  description: 'You are a helpful assistant.',
  apiKey: '',
  baseURL: 'http://localhost:8080/v1',
});

const response = await ollama.execute('What can you run locally?');

// Discover which models are available on the server
const models = await ollama.listModels();

Custom OpenAI-compatible server (vLLM, LM Studio, Together AI, Groq, …): extend OpenAICompatibleAgent directly:

import { OpenAICompatibleAgent, OpenAICompatibleConfig } from '@agentionai/agents/llamacpp';

class VLLMAgent extends OpenAICompatibleAgent {
  constructor(config: Omit<OpenAICompatibleConfig, 'vendor'>) {
    super({ ...config, vendor: 'llamacpp', baseURL: config.baseURL ?? 'http://localhost:8000/v1' });
  }
  protected getVendorName() { return 'vLLM'; }
}

Full guide →

Built-In Tools

Use a provider's own server-side tools (executed by the provider, not locally) alongside your custom tools:

import { ClaudeAgent, webSearchTool } from '@agentionai/agents/claude';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'researcher',
  name: 'Researcher',
  description: 'You are a helpful research assistant with web access.',
  model: 'claude-sonnet-4-6',
  builtInTools: [webSearchTool({ maxUses: 5 })],
});

const response = await agent.execute('What happened in the news today?');

Streaming

All three major providers support streaming via executeStream(), which returns an AsyncGenerator<StreamChunk>. Each chunk is { type: "text" | "reasoning"; content: string } — text for visible output, reasoning for internal thinking tokens (DeepSeek R1, Claude extended thinking, OpenAI o-series).

import { ClaudeAgent } from '@agentionai/agents/claude';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'assistant',
  name: 'Assistant',
  description: 'You are a helpful assistant.',
});

for await (const chunk of agent.executeStream('Tell me a story')) {
  if (chunk.type === 'text') process.stdout.write(chunk.content);
}

Tool calls are handled transparently — the generator continues streaming after each round-trip. The same API works across ClaudeAgent, OpenAiAgent, and LlamaCppAgent / any OpenAICompatibleAgent subclass.

Multi-Agent Pipeline

Chain agents together with different providers and models:

import { ClaudeAgent } from '@agentionai/agents/claude';
import { OpenAiAgent } from '@agentionai/agents/openai';
import { Pipeline } from '@agentionai/agents/core';

const researcher = new OpenAiAgent({
  apiKey: process.env.OPENAI_API_KEY,
  id: 'researcher',
  name: 'Researcher',
  description: 'Research the given topic and provide key facts.',
  model: 'gpt-4o',
  tools: [searchTool],
});

const writer = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'writer',
  name: 'Writer',
  description: 'Write a blog post based on the research provided.',
  model: 'claude-sonnet-4-5',
});

const pipeline = new Pipeline([researcher, writer]);
const result = await pipeline.execute('Renewable energy trends in 2024');

Agent Delegation

Use agents as tools for hierarchical workflows:

import { ClaudeAgent } from '@agentionai/agents/claude';
import { OpenAiAgent } from '@agentionai/agents/openai';

// Research assistant (cheaper model for data gathering)
const researchAssistant = new OpenAiAgent({
  apiKey: process.env.OPENAI_API_KEY,
  id: 'research-assistant',
  name: 'Research Assistant',
  description: 'Search and summarize information on topics.',
  model: 'gpt-4o-mini',
  tools: [searchTool],
});

// Lead researcher delegates to assistant, synthesizes findings
const researcher = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'researcher',
  name: 'Lead Researcher',
  description: 'Research topics thoroughly using your assistant.',
  model: 'claude-sonnet-4-5',
  agents: [researchAssistant],  // Assistant available as a tool
});

const result = await researcher.execute('Latest developments in quantum computing');

Multimodal / Vision

Send images alongside text using imageUrl() or imageBase64(). The same MessageContent[] interface works across all providers:

import { ClaudeAgent } from '@agentionai/agents/claude';
import { imageUrl, imageBase64 } from '@agentionai/agents/core';
import * as fs from 'fs';

const agent = new ClaudeAgent({
  apiKey: process.env.ANTHROPIC_API_KEY,
  id: 'vision-agent',
  name: 'VisionAgent',
  description: 'You analyze images.',
  model: 'claude-opus-4-6',
});

// Remote image by URL
const response = await agent.execute([
  imageUrl('https://example.com/chart.png'),
  { type: 'text', text: 'Summarize this chart in one sentence.' },
]);

// Local image as base64
const data = fs.readFileSync('./photo.jpg').toString('base64');
const response2 = await agent.execute([
  imageBase64(data, 'image/jpeg'),
  { type: 'text', text: 'What plant is this?' },
]);

Core Concepts

Agents

Unified interface across Claude, OpenAI, Gemini, Mistral, and local models via Ollama and llama.cpp. Tools, history, and token tracking built-in.

Learn more →

Tools

JSON Schema + handler pattern. Unique capability: wrap any agent as a tool for delegation hierarchies. Also supports provider-defined built-in tools (e.g. Anthropic's web search, bash, text editor) that run server-side.

Learn more →

Context Management

Tool result masking (lossless, free) + rolling summarization (auto-firing) + sub-agent delegation (token isolation by architecture). Composable plugins keep the context window lean automatically.

Learn more → · History API →

Multimodal / Vision

Unified MessageContent[] interface for images across all providers. URL and base64 images, mix text and images freely in a single call.

Learn more →

Graph Pipelines

Compose sequential, parallel, voting, routing, and nested graphs. Mix models and providers freely.

Learn more →

RAG & Vector Stores

LanceDB vector store, token-aware chunking, ingestion pipeline, and retrieval tools out of the box.

Learn more →

Observability

Per-call and per-node token counts, duration metrics, full execution visibility.

Learn more →

Documentation

• Getting Started - Installation and first agent
• Context Management - Token budgets, masking, and compression
• Agents - Agent configuration and providers
• Tools - Adding capabilities and agent delegation
• Multimodal / Vision - Sending images across all providers
• History - Conversation persistence and plugins
• Graph Pipelines - Multi-agent workflows
• Vector Stores - RAG and semantic search
• Examples - Real-world implementations
• API Reference - Full API documentation

Why Agention?

• Ship faster — Stop rebuilding agent infrastructure for every project
• Stay flexible — Swap providers, mix models, customize everything
• Keep control — See exactly what's happening at every step
• Scale confidently — Built-in metrics, token tracking, and observability

Examples

Check out the examples directory for complete working examples:

• Basic agents with different providers
• Custom tools and agent delegation
• Sequential, parallel, and voting pipelines
• RAG applications with vector search
• Document ingestion and chunking

Built with Agention

• Marshall — a coding agent for open weights. Runs a planner/coder/reviewer loop entirely on local hardware via llama.cpp or Ollama, no API key, account, or cloud required — with approval-gated file writes and shell commands, and support for mixing local and paid models across roles.

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Links

• Documentation
• GitLab
• npm
• Issues