Getting Started

Installation

Use Node.js 22.13+ or 24+. Install the published unscoped v2 beta:

bash

npm install oneringai

The published package is oneringai@2.0.0-beta.1; both latest and next currently select this beta. For source development, follow the local-package recipe. ESM and CommonJS outputs and declarations are supplied. Optional SDK, Mongo, and native desktop dependencies are needed only for their respective integrations.

Environment Setup

Create a .env file in your project root, keep it out of Git, and load it in your application (for example, Node's --env-file=.env flag). Merely creating the file does not populate process.env for the library:

env

# AI Provider Keys
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GOOGLE_API_KEY=...
GROQ_API_KEY=...
XAI_API_KEY=xai-...

# Optional: OAuth encryption key for external APIs
OAUTH_ENCRYPTION_KEY=your-32-byte-hex-key

First Agent

typescript

// Documentation check: complete example
import { Connector, Agent, Vendor } from 'oneringai';

// 1. Create a connector (authentication)
Connector.create({
  name: 'openai',
  vendor: Vendor.OpenAI,
  auth: { type: 'api_key', apiKey: process.env.OPENAI_API_KEY! },
});

// 2. Create an agent
const agent = Agent.create({
  connector: 'openai',
  model: 'gpt-5.6-terra',
});

// 3. Run, then release the agent and its resources.
try {
  const response = await agent.run('What is the capital of France?');
  console.log(response.output_text);
} finally {
  agent.destroy();
}