Gneol SDK

Build and manage multi‑agent orchestration programs with TypeScript.

Gneol is a multi‑agent orchestration framework. A .gneol program is a declarative script that defines agents, models, triggers, tools, and integrations — instructing the runtime how to coordinate autonomous AI agents to accomplish complex tasks.

The Gneol SDK lets you create, edit, compile, and deploy .gneol programs from TypeScript or JavaScript. Instead of writing raw script files, you use a typed, fluent API — then compile to .gneol and deploy via the Gneol CLI.

npm install gneol-sdk

Prerequisites

• Node.js v16 or later
• Gneol CLI – required for deploy(). Gneol ships as a single self-contained binary (no npm package). Install it with:

  curl -sSL https://raw.githubusercontent.com/Gneol/Gneol/main/install.sh | bash

  The runtime handles execution of compiled .gneol programs — run gneol --help for details.

Quick Start (30 seconds)

Create a minimal program, compile it, and see the output:

import { Gneol } from 'gneol-sdk';

async function main() {
  const sdk = new Gneol({ store: 'file', path: './programs' });
  await sdk.program.create({ id: 'hello', name: 'Hello World' });
  const program = await sdk.program.fetch('hello');
  program.header.set({ name: 'Hello World', model: 'deepseek-v4-flash' });
  await program.subagents.create({
    name: 'HealthBot',
    model: 'deepseek-v4-flash',
    description: 'Runs periodic health checks.',
  });
  await program.triggers.create({
    timeExpr: 'every:10min',
    do: ['Log health check.'],
    subagent: 'HealthBot',
  });
  console.log(program.compile());
  await program.save();
  // Requires Gneol CLI — see prerequisites
  await program.deploy();
}

main().catch(console.error);

The Problem It Solves

Imagine you run a SaaS product and want an autonomous customer support triage system:

• Users submit tickets via a webhook.
• A billing specialist agent handles payment issues using a fast, cheap model.
• A technical support agent troubleshoots bugs and escalates complex cases to senior engineers.
• A summarization step condenses resolved tickets into a daily report.
• A scheduled trigger escalates tickets that have been open for more than 4 hours.
• An external API (via MCP) looks up account details to enrich the context.

Without an orchestration framework, you’d need to build a custom state machine, manage retries, handle agent switching, and wire everything together. With Gneol and this SDK, you declare the system in a few dozen lines of code, compile it to a .gneol script, and deploy it to the Gneol runtime.

Example: Customer Support Triage System

This example builds the system described above. It demonstrates every major directive type: header, models, subagents, summarization, tools, MCP, triggers, and imports.

1. Initialize the SDK

import { Gneol } from 'gneol-sdk';

const sdk = new Gneol({ store: 'file', path: './programs' });

The directory is created automatically. Each program is stored as <id>.json.

2. Create the Program

await sdk.program.create({ id: 'support-triage', name: 'Support Triage' });
const program = await sdk.program.fetch('support-triage');

3. Define Models

// Fast, cheap model for billing
await program.models.create({
  name: 'billing-model',
  provider: 'openrouter',
  modelId: 'openai/gpt-4o-mini',
  apiKey: 'OPENROUTER_API_KEY',
  temperature: 0.1,
  maxTokens: 1024,
});

// Powerful model for technical deep dives
await program.models.create({
  name: 'tech-model',
  provider: 'openrouter',
  modelId: 'openai/gpt-4o',
  apiKey: 'OPENROUTER_API_KEY',
  temperature: 0.3,
  maxTokens: 4096,
});

// Model for summarization
await program.models.create({
  name: 'summary-model',
  provider: 'openrouter',
  modelId: 'anthropic/claude-3-haiku',
  apiKey: 'ANTHROPIC_API_KEY',
  temperature: 0.0,
  maxTokens: 2048,
});

4. Add an MCP Server (Account Lookup)

MCP servers connect external tools directly into the agent runtime.

await program.mcp.create({
  name: 'account-db',
  config: JSON.stringify({
    type: 'http',
    url: 'https://internal-api.example.com/mcp',
  }),
});

5. Add a Custom Tool Script

A local script that runs on the agent’s machine to perform ticket lookup.

await program.tools.create({
  name: 'ticket-lookup',
  script: './tools/ticket-lookup.js',
  description: 'Search and retrieve customer support tickets by ID or email.',
});

6. Define Subagents (Specialized Agents)

Subagents are autonomous agents each with their own model and specialty. They compile to subagent("Name") directives.

Each subagent gets its own model and specialty. Route a trigger to a specific subagent with the subagent field.

await program.subagents.create({
  name: 'BillingBot',
  model: 'billing-model',
  description: 'Handles payment, refund, and invoice inquiries.',
});

await program.subagents.create({
  name: 'TechBot',
  model: 'tech-model',
  description: 'Diagnoses technical issues and escalates to senior engineers.',
});

await program.subagents.create({
  name: 'EscalationManager',
  model: 'tech-model',
  description: 'Monitors open tickets and escalates stalled ones.',
});

7. Configure Summarization

await program.summarizations.create({
  model: 'summary-model',
  prompt: 'Summarize all resolved tickets in the last 24 hours. Group by category (billing, technical, other) and include resolution time.',
});

8. Add Triggers

// Scheduled escalation check every 30 minutes
await program.triggers.create({
  timeExpr: 'every:30min',
  do: ['Run escalation check for tickets older than 4 hours.'],
  subagent: 'EscalationManager',
  max: 48, // 48 runs × 30min interval = 24 hours of coverage
});

// Event-driven trigger: new ticket arrives via webhook
await program.triggers.create({
  eventName: 'new-ticket',
  do: ['Classify ticket by category.', 'Route to appropriate subagent.'],
  maxSize: 10,  // fire when 10 pending jobs accumulate
  delay: 5,     // debounce 5 seconds
});

// Daily summary report
await program.triggers.create({
  timeExpr: '9am',
  do: ['Generate daily support summary.'],
});

9. Import Shared Utilities

program.imports.add('shared/escalation-policies.gneol');
program.imports.add('shared/notification-templates.gneol');

10. Compile and Save

console.log(program.compile());
await program.save();

11. Deploy to the Gneol Runtime

Deployment requires the Gneol CLI to be installed and on your PATH. The SDK writes the compiled .gneol file to disk and runs gneol deploy -f <file>.

await program.deploy();
// Writes ./support-triage.gneol and runs:
//   gneol deploy -f ./support-triage.gneol

The Gneol runtime (separate from this SDK) handles execution, monitoring, debugging, and rollback — see its documentation for details. For versioning, keep your SDK source files and compiled .gneol output under version control (e.g., git). To roll back to a previous deployment, check out the desired version and re-run program.deploy().

Generated Output

The compiled .gneol script looks like this:

program("Support Triage")
  .model("billing-model")
model("billing-model")
  .provider("openrouter")
  .modelId("openai/gpt-4o-mini")
  .apiKey("OPENROUTER_API_KEY")
  .temperature(0.1)
  .maxTokens(1024)
model("tech-model")
  .provider("openrouter")
  .modelId("openai/gpt-4o")
  .apiKey("OPENROUTER_API_KEY")
  .temperature(0.3)
  .maxTokens(4096)
model("summary-model")
  .provider("openrouter")
  .modelId("anthropic/claude-3-haiku")
  .apiKey("ANTHROPIC_API_KEY")
  .temperature(0.0)
  .maxTokens(2048)
mcp("account-db")
  .config('{"type":"http","url":"https://internal-api.example.com/mcp"}')
tool("ticket-lookup")
  .script("./tools/ticket-lookup.js")
  .description("Search and retrieve customer support tickets by ID or email.")
subagent("BillingBot")
  .model("billing-model")
  .description("Handles payment, refund, and invoice inquiries.")
subagent("TechBot")
  .model("tech-model")
  .description("Diagnoses technical issues and escalates to senior engineers.")
subagent("EscalationManager")
  .model("tech-model")
  .description("Monitors open tickets and escalates stalled ones.")
summarization()
  .model("summary-model")
  .prompt("Summarize all resolved tickets in the last 24 hours.")
at("every:30min")
  .do("Run escalation check for tickets older than 4 hours.")
  .subagent("EscalationManager")
  .max(48)
on("new-ticket")
  .do("Classify ticket by category.")
  .do("Route to appropriate subagent.")
  .maxSize(10)
  .delay(5)
at("9am")
  .do("Generate daily support summary.")
import('shared/escalation-policies.gneol')
import('shared/notification-templates.gneol')

Quick Reference

| Directive | SDK Accessor | Key Methods | |-----------|--------------|-------------| | Header | program.header | .set(), .get(), .clear() | | Model | program.models | .create(), .list(), .update(), .delete() | | Subagent | program.subagents | .create(), .list(), .update(), .delete() | | Summarization | program.summarizations | .create(), .list(), .update(), .delete() | | Tool | program.tools | .create(), .list(), .update(), .delete() | | MCP | program.mcp | .create(), .list(), .update(), .delete() | | Trigger (at / on) | program.triggers | .create(), .list(), .update(), .delete() | | Import | program.imports | .add(), .list(), .remove() |

Once you’ve composed your program, call:

• program.compile() → get the .gneol source.
• program.save() → persist to the store.
• program.deploy() → write to disk and invoke gneol deploy -f.

Debugging

Before deploying, inspect the generated script by calling program.compile() and logging the output — this is the best way to catch issues early. For runtime debugging (execution logs, agent traces, trigger history), refer to the Gneol runtime documentation — the SDK compiles and deploys but does not manage runtime diagnostics.

Storage

Programs are persisted as JSON files (<id>.json) in the configured directory. The directory is auto‑created on initialization.

To use a custom backend (Redis, SQLite, Postgres, etc.), implement the Database interface:

interface Database {
  get(key: string): Promise<any>;
  set(key: string, value: any): Promise<void>;
  delete(key: string): Promise<void>;
  list(): Promise<string[]>;
}

Pass your implementation directly:

const sdk = new Gneol({ store: myDatabase });

To test SDK logic without persistence, create a mock Database. The interface uses any for flexibility — you can type it strictly in your implementation.

Run the Example

npx tsx examples/basic-usage.ts

License

MIT © Gneol AI Platform