Connections

A Connection is the interface between KyroActor and your AI agent. It handles sending messages and waiting for responses.

Connection interface

interface Connection {
  send(message: string): Promise<void>;
  waitForMessage(): Promise<string>;
  close(): Promise<void>;
}

You can implement this interface for any transport layer. Kyro ships two built-in implementations.

WebSocketConnection

Connects to any WebSocket server that accepts plain text messages and replies in kind.

Install

npm install ws
npm install --save-dev @types/ws

Usage

import { Actor, WebSocketConnection } from '@kyro/actor';
import { ProviderFactory } from '@kyro/shared';
 
const provider = ProviderFactory.create({ provider: 'openai', model: 'gpt-4o' });
const actor = new Actor('./personality.yaml', provider);
 
const connection = new WebSocketConnection('ws://localhost:3000/agent');
const transcript = await actor.run('./scenario.yaml', connection);

Message format

By default, WebSocketConnection sends raw strings and expects raw string replies. If your WebSocket server uses JSON, wrap it with a custom connection:

import { WebSocketConnection } from '@kyro/actor';
 
class JsonWsConnection extends WebSocketConnection {
  async send(message: string) {
    await super.send(JSON.stringify({ type: 'user', content: message }));
  }
 
  async waitForMessage(): Promise<string> {
    const raw = await super.waitForMessage();
    return JSON.parse(raw).content;
  }
}

LangChainConnection

Connects to any LangChain Runnable (chain, agent, or graph) using @langchain/core.

Install

npm install @langchain/core

ℹInfo

@langchain/core is a peer dependency — install it in your project alongside @kyro/actor.

Usage

import { Actor, LangChainConnection } from '@kyro/actor';
import { ProviderFactory } from '@kyro/shared';
import { createMyAgent } from './my-agent'; // your LangChain agent
 
const provider = ProviderFactory.create({ provider: 'anthropic', model: 'claude-opus-4-6' });
const actor = new Actor('./personality.yaml', provider);
 
const agent = createMyAgent();
const connection = new LangChainConnection(agent);
 
const transcript = await actor.run('./scenario.yaml', connection);

Custom connections

Implement the Connection interface directly for any other transport (HTTP, gRPC, etc.):

import type { Connection } from '@kyro/actor';
 
class HttpConnection implements Connection {
  private sessionId: string;
 
  constructor(private url: string) {
    this.sessionId = crypto.randomUUID();
  }
 
  async send(message: string): Promise<void> {
    await fetch(this.url, {
      method: 'POST',
      body: JSON.stringify({ sessionId: this.sessionId, message }),
      headers: { 'Content-Type': 'application/json' },
    });
  }
 
  async waitForMessage(): Promise<string> {
    const res = await fetch(`${this.url}/poll?sessionId=${this.sessionId}`);
    const { reply } = await res.json();
    return reply;
  }
 
  async close(): Promise<void> {
    // cleanup
  }
}

On this page