opensearch-project/agent-health/add-connector

Connector System (services/connectors/)

Pluggable abstraction for agent communication protocols.

Key Files

• types.ts: AgentConnector, ConnectorRequest, ConnectorResponse interfaces
• registry.ts: Singleton connectorRegistry — get(), getForAgent()
• base/BaseConnector.ts: Abstract base with auth header building
• index.ts: Browser-safe exports (no Node.js deps)
• server.ts: All connectors including Node.js-only (subprocess, claude-code)

Built-in Connectors

Usage

import { connectorRegistry } from '@/services/connectors';
const connector = connectorRegistry.getForAgent(agentConfig);
const response = await connector.execute(endpoint, request, auth, onProgress);

Creating a Custom Connector

import { BaseConnector } from '@/services/connectors';
class CustomConnector extends BaseConnector {
  readonly type = 'custom' as const;
  readonly name = 'My Custom Agent';
  readonly supportsStreaming = true;
  async execute(endpoint, request, auth, onProgress) {
    // Your protocol implementation
  }
}
connectorRegistry.register(new CustomConnector());

Trace correlation & subprocess hooks

• Trace context propagation is handled by BaseConnector — set

connectorConfig.traceContext so the agent's spans join the eval test_case trace tree:

• propagateEnv: true → inject TRACEPARENT env into subprocess agents (buildTraceparentEnv()).
• propagateHeader: true → inject a traceparent HTTP header into HTTP/SSE agents (injectTraceparentHeaders()).
• serviceName: '<otel-service-name>' → service-name + time-window fallback. Defaults: claude-code-agent, kiro-agent, pi-agent, observio-sample-agent. See the "Trace correlation conventions" section in AGENTS.md.
• Subprocess connectors (SubprocessConnector subclasses) can override

parseStderrChunk(chunk, trajectory, onProgress, state) to turn stderr markers into trajectory steps (how kiro surfaces [tool] Running: / [tool] status: as action + tool_result steps). The base class persists stderr to rawOutput and honors per-request connectorConfig overrides (args / inputMode / timeout). Keep ALL streaming state (partial-line buffers, pending tool names, captured ids) on the per-invocation state object (extend SubprocessExecutionState via createExecutionState()), never on this — the registry shares one connector instance across concurrent runs.