Skip to content
BranchesTags

Repository files navigation

AgentOS TS

The Open Source Operating System for AI Agents

A comprehensive TypeScript framework for building production-ready AI agent applications using LangGraph.

npm version License: MIT TypeScript Node.js Version

🚀 Quick Start

Installation

# Install the CLI globally
npm install -g @agentic-os/cli

# Or use npx
npx @agentic-os/cli init my-agent

Create Your First Agent

import { AgentOS } from '@agentic-os/core';
import { OpenAIProvider } from '@agentic-os/providers';
import { CoderAgent } from '@agentic-os/agents';

// Initialize the provider
const provider = new OpenAIProvider({
  apiKey: process.env.OPENAI_API_KEY
});

// Create your agent
const agent = new CoderAgent({
  name: 'my-coder',
  provider,
  model: 'gpt-4o'
});

// Run the agent
const result = await agent.run({
  task: 'Create a REST API with Fastify'
});

console.log(result);

📦 Packages

Package Version Description
@agentic-os/core 1.0.0 Core domain types, entities, Result pattern
@agentic-os/config 1.0.0 Type-safe configuration with Zod
@agentic-os/providers 1.0.0 Multi-provider LLM integration
@agentic-os/graph 1.0.0 LangGraph orchestration system
@agentic-os/agents 1.0.0 Pre-built AI agents
@agentic-os/memory 1.0.0 Multi-tier memory system
@agentic-os/mcp 1.0.0 MCP adapters for external services
@agentic-os/rag 1.0.0 RAG pipeline utilities
@agentic-os/auth 1.0.0 JWT, API Keys, RBAC
@agentic-os/telemetry 1.0.0 Observability primitives
@agentic-os/cli 1.0.0 Command-line interface

🔌 Supported LLM Providers

AgentOS supports multiple LLM providers out of the box:

Provider Streaming Function Calling Vision Embeddings
OpenAI ✅ ✅ ✅ ✅
Anthropic ✅ ✅ ✅ -
Google Gemini ✅ ✅ ✅ ✅
Groq ✅ ✅ - ✅
OpenRouter ✅ ✅ ✅ ✅
Ollama ✅ - - ✅
Azure OpenAI ✅ ✅ ✅ ✅
DeepSeek ✅ ✅ - ✅

Usage Example

import { ProviderManager } from '@agentic-os/providers';

// Create provider manager
const manager = new ProviderManager();

// Register providers
manager.register('openai', {
  apiKey: process.env.OPENAI_API_KEY
});

manager.register('anthropic', {
  apiKey: process.env.ANTHROPIC_API_KEY
});

// Use any provider
const provider = manager.get('openai');
const response = await provider.chat({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }]
});

🤖 Pre-built Agents

AgentOS comes with 13 pre-built agents ready to use:

Agent Description
Research Agent Web research and fact-finding
Planner Agent Task decomposition and planning
Coder Agent Code generation and debugging
Reviewer Agent Code review and analysis
Memory Agent Memory management and retrieval
Support Agent Customer support automation
Finance Agent Financial analysis and reporting
Vision Agent Image analysis and description
Email Agent Email composition and management
Browser Agent Web browsing automation
SQL Agent Database queries and analysis
Supervisor Agent Multi-agent coordination
Judge Agent Quality assessment and decisions

Example: Using a Pre-built Agent

import { ResearchAgent } from '@agentic-os/agents';

const agent = new ResearchAgent({
  provider: openAIProvider,
  maxSources: 10
});

const results = await agent.run({
  query: 'Latest developments in quantum computing',
  format: 'detailed'
});

🧠 Memory System

Multi-tier memory architecture:

Memory Type Description
Working Memory Short-term, high-speed cache
Conversation Memory Session context
Summary Memory Compressed summaries
Semantic Memory Embedding-based storage
Long-term Memory Persistent storage

Supported Backends

  • Redis - High-performance caching
  • PostgreSQL - Persistent storage
  • SQLite - Local development
import { MemoryManager, RedisAdapter } from '@agentic-os/memory';

const memory = new MemoryManager({
  adapter: new RedisAdapter({
    url: process.env.REDIS_URL
  }),
  tiers: ['working', 'conversation', 'semantic']
});

// Store and retrieve
await memory.store('user:123', { context: 'user preferences' });
const data = await memory.retrieve('user:123');

🔗 MCP Adapters

Connect to external services via Model Context Protocol:

Service Capabilities
GitHub Repos, Issues, PRs, Actions
Slack Messages, Channels, Users
Discord Servers, Channels, Messages
Notion Pages, Databases
Google Drive Files, Folders, Permissions
Linear Issues, Projects, Teams
Jira Issues, Boards, Projects
Stripe Customers, Payments, Subscriptions
Mercado Pago Payments, Subscriptions
Postgres Query, Schema, Tables
Redis Keys, Strings, Lists
SQLite Query, Schema
Filesystem Read, Write, List 
import { MCPClient } from '@agentic-os/mcp';
import { GitHubAdapter } from '@agentic-os/mcp/adapters';

const client = new MCPClient({
  adapters: [
    new GitHubAdapter({ token: process.env.GITHUB_TOKEN }),
    new SlackAdapter({ token: process.env.SLACK_TOKEN })
  ]
});

const issues = await client.github.issues.list({ owner: 'owner', repo: 'repo' });

📚 RAG Pipeline

Full-featured Retrieval Augmented Generation:

Loaders

  • PDF, Markdown, DOCX, CSV, HTML
  • Notion, Confluence, GitHub, Google Drive

Chunkers

  • Recursive character splitting
  • Semantic chunking
  • Token-based chunking

Vector Stores

  • Pinecone, Qdrant, Weaviate, Chroma
  • In-memory for development

Embedders

  • OpenAI, Cohere, Ollama

Search

  • Similarity search
  • Hybrid search (keyword + vector)
  • MMR (Maximal Marginal Relevance)
import { RAGPipeline } from '@agentic-os/rag';
import { PDFLoader, RecursiveChunker } from '@agentic-os/rag';

const pipeline = new RAGPipeline({
  loader: new PDFLoader({ path: './document.pdf' }),
  chunker: new RecursiveChunker({ chunkSize: 1000 }),
  embedder: openAIEmbedder,
  vectorStore: pineconeStore
});

await pipeline.index();
const results = await pipeline.query('What is this document about?');

🔐 Authentication & Security

JWT Authentication

import { JWTService } from '@agentic-os/auth';

const jwt = new JWTService({
  secret: process.env.JWT_SECRET,
  expiresIn: '1h'
});

const token = await jwt.sign({ userId: '123', role: 'admin' });
const payload = await jwt.verify(token);

API Keys

import { APIKeyService } from '@agentic-os/auth';

const apiKeys = new APIKeyService({
  storage: postgresStorage
});

const key = await apiKeys.create({ name: 'Production', permissions: ['read', 'write'] });

RBAC (Role-Based Access Control)

import { RBACService } from '@agentic-os/auth';

const rbac = new RBACService();

rbac.defineRole('admin', ['read', 'write', 'delete']);
rbac.defineRole('user', ['read']);

const allowed = rbac.check('admin', 'delete'); // true

📊 Telemetry

Built-in observability with OpenTelemetry:

import { createTelemetry } from '@agentic-os/telemetry';

const telemetry = createTelemetry({
  serviceName: 'my-agent',
  otlpEndpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT
});

// Tracing
const span = telemetry.startSpan('process-task');
await processTask();
span.end();

// Metrics
telemetry.recordMetric('requests_total', 1, ['method:GET']);
telemetry.recordHistogram('request_duration_ms', duration);

// Logging
telemetry.log.info('Task completed', { taskId: '123' });

Health Checks

import { HealthCheck } from '@agentic-os/telemetry';

const health = new HealthCheck();

health.register('database', async () => {
  await db.ping();
  return 'healthy';
});

const status = await health.check();
// { status: 'healthy', checks: { database: 'healthy' } }

🖥️ Dashboard

A Next.js dashboard for monitoring:

# Start the dashboard
cd apps/dashboard
pnpm dev

Features:

  • Real-time metrics (tokens, latency, costs)
  • Thread management
  • Execution history
  • Memory visualization
  • Log viewer
  • Trace exploration
  • Provider status
  • Health monitoring

🛠️ CLI

# Initialize a new project
agentos init my-agent

# Create a new agent
agentos new agent --name my-agent --type coder

# Run an agent
agentos run my-agent

# Check system health
agentos doctor

🐳 Docker

# docker-compose.yml
version: '3.8'
services:
  api:
    image: agentos/api:latest
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgres://...
      - REDIS_URL=redis://...
      - JWT_SECRET=${JWT_SECRET}

  dashboard:
    image: agentos/dashboard:latest
    ports:
      - "3001:3000"
    environment:
      - API_URL=http://api:3000

  prometheus:
    image: prom/prometheus:latest
    volumes:
      - ./docker/prometheus.yml:/etc/prometheus/prometheus.yml

📖 Documentation

🧪 Testing

# Run all tests
pnpm test

# Run with coverage
pnpm test --coverage

# Run e2e tests
pnpm test:e2e

📝 License

MIT License - see LICENSE for details.

🤝 Contributing

Contributions are welcome! Please read our Contributing Guide before submitting PRs.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'feat: add amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

📬 Contact

Built with ❤️ by Gilberto

About

TypeScript framework for building production-ready AI agent applications with LangGraph — multi-provider LLMs, RAG, tiered memory, and MCP adapters.

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages