@evolutese/runtime

Core agent execution engine for the Evolutese platform. Handles intent resolution, LLM routing, multi-step graph execution, memory, and checkpointing.

Most developers interact with the runtime indirectly through @evolutese/sdk. Use this package directly when you need low-level control or want to build your own integration layer.

Installation

npm install @evolutese/runtime

LLM providers

| Provider | id | Notes | |----------|----|-------| | OpenAI | openai | GPT-4o and family | | Anthropic | anthropic | Claude | | Google | google | Gemini | | Ollama | ollama | Local models, no API key — runs on localhost:11434 | | OpenRouter | openrouter | 200+ models via openrouter.ai |

Bootstrap

import { bootstrapRuntime, getCoreRuntimeInstance, RuntimePresenter } from '@evolutese/runtime';

await bootstrapRuntime({
  connectors: { mongo: myMongoConnector },
  presenter:  new RuntimePresenter(),
});

const runtime = getCoreRuntimeInstance();
await runtime.executeIntent(
  { agentId: 'invoice', intentId: 'draft_invoice', actionId: 'draft_invoice', input: { customer: 'Alice', amount: 200 } },
  { tenantId: 'default' }
);

LLM environment variables

The runtime picks up provider configuration from env vars automatically:

| Variable | Purpose | |----------|---------| | LLM_PROVIDER | Default provider (openai, google, anthropic, ollama, openrouter) | | LLM_API_KEY | API key for the default provider | | LLM_MODEL | Default model name |

OPENAI_API_KEY and OPENAI_MODEL are still accepted as fallbacks.

Custom LLM configuration

import { llmService } from '@evolutese/runtime';

// Override model or base URL per provider
llmService.configure('ollama', { baseURL: 'http://192.168.1.5:11434/v1', model: 'llama3.2' });

Thread management

import { threadManager } from '@evolutese/runtime';

// Delete a thread and all its messages
await threadManager.deleteThread('thread-id-123');

threadManager implements IThreadManager:

| Method | Description | |--------|-------------| | addMessage(threadId, message) | Append a message to a thread | | getThread(threadId) | Retrieve a thread by ID | | deleteThread(threadId) | Delete a thread and its history |

Pluggable interfaces

| Interface | Purpose | |-----------|---------| | AgentResolver | Custom agent lookup — replace or extend the YAML registry | | IStateManager | Execution state storage — swap in Redis or Postgres | | IPresenter | Output formatting — JSON, PDF, HTML | | RuntimePlugin | Lifecycle hooks — run logic before any intent executes | | LLMProvider | Custom LLM backend — any OpenAI-compatible endpoint |

Browser-safe entrypoint

For frontend bundlers use the /client sub-path — no Node.js APIs:

import type { AgentDefinition, FlowStep } from '@evolutese/runtime/client';
import { consumeEvoluteseStream } from '@evolutese/runtime/client';

License

MIT