ProviderObserver

SUPPORT · interface · Type contract

The caller can correlate each observation using the original, request-local model options.

Import

TypeScript

import type { ProviderObserver } from '@jangts/agent-core/support';

JavaScript

/** @typedef {import('@jangts/agent-core/support').ProviderObserver} ProviderObserver */

Other public entry points:@jangts/agent-core/types, @jangts/agent-core/structs, @jangts/agent-core/support, @jangts/agent-core/support/model.

Definition

interface ProviderObserver

Field structure

Field	Type	Required	Description
accepts	((descriptor: ProviderEventDescriptor, options: Readonly<ModelProviderContext>) => boolean) | undefined	Optional	Returns false to skip an event; absent means accept every event.
write	(event: ProviderObservation, options: Readonly<ModelProviderContext>) => void | Promise<void>	Required	Handles one observation. Throwing or rejecting never affects the provider call.

Member index

Member	Purpose
write	Handles one observation. Throwing or rejecting never affects the provider call.

Member details

write

Handles one observation. Throwing or rejecting never affects the provider call.

ProviderObserver.write(event: ProviderObservation, options: Readonly<ModelProviderContext>): void | Promise<void>

Handles one observation. Throwing or rejecting never affects the provider call.

Parameter	Type	Passing	Description
event	ProviderObservation	Required	—
options	Readonly<ModelProviderContext>	Required	—

Fields of options

Field	Type	Required	Description
options	Readonly<ModelOptions> | undefined	Optional	Read-only. Options prepared for this call, including function schemas and JSON mode.
logger	SubFlowLog | undefined	Optional	Read-only. Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	Required	Read-only. Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	Optional	Read-only. Diagnostic scope of the enclosing call, when recording is enabled.

Optional shapes of Parameter event: choose one shape; required fields for each branch are listed separately.

Branch 1

Field	Type	Required	Description
event	"provider.request"	Required	Read-only. See the type definition and usage context.
payload	{ url: string; body: unknown; }	Required	Read-only. See the type definition and usage context.

Branch 2

Field	Type	Required	Description
event	"provider.response"	Required	Read-only. See the type definition and usage context.
payload	{ status: number; requestId: string | null; contentType: string | null; }	Required	Read-only. See the type definition and usage context.

Branch 3

Field	Type	Required	Description
event	"provider.frame"	Required	Read-only. See the type definition and usage context.
payload	{ data: string; }	Required	Read-only. See the type definition and usage context.

Branch 4

Field	Type	Required	Description
event	"provider.error-body"	Required	Read-only. See the type definition and usage context.
payload	{ status: number; body: string; truncated?: boolean; }	Required	Read-only. See the type definition and usage context.

Branch 5

Field	Type	Required	Description
event	"provider.end"	Required	Read-only. See the type definition and usage context.
payload	{ complete: boolean; error?: unknown; }	Required	Read-only. See the type definition and usage context.

Returns: void \| Promise<void>.

Awaited value: void.

Examples

• Provider observation and the App's own recording targets: A stable Provider binds observation rules; each request is associated only with its own target, and child scopes inherit the association.

Observe metadata only

Beginner · Node.js

TypeScript

import { Support } from '@jangts/agent-core';
const scope = Support.createProviderObservationScope<{ requestId: string }>({
  accepts(_owner, descriptor) { return descriptor.content === 'metadata'; },
  write(owner, event, spanId) { console.log(owner.requestId, spanId, event.event); },
});
console.log(scope.observer);

JavaScript

import { Support } from '@jangts/agent-core';
const scope = Support.createProviderObservationScope({
    accepts(_owner, descriptor) { return descriptor.content === 'metadata'; },
    write(owner, event, spanId) { console.log(owner.requestId, spanId, event.event); },
});
console.log(scope.observer);

Bind your own correlation value per request

Configuration · Node.js

This example only assembles; for actual calls, configure that diagnostics into the corresponding request execution rather than forcing an App ID into the Core identity.

TypeScript

import { Support } from '@jangts/agent-core';
import { createDiagnostics } from '@jangts/agent-core/diagnostics';
const scope = Support.createProviderObservationScope<{ requestId: string }>({
  accepts: (_owner, descriptor) => descriptor.content === 'metadata',
  write(owner, event, spanId) { console.log(owner.requestId, spanId, event.event); },
});
const provider = new Support.CompatibleModelProvider({
  config: { baseUrl: process.env.MODEL_BASE_URL!, apiKey: process.env.MODEL_API_KEY!, model: process.env.MODEL_NAME! },
  observe: { provider: scope.observer },
});
const diagnostics = scope.attach(createDiagnostics(), { requestId: 'app-request-1' });
console.log(provider, diagnostics.identity?.runId);

JavaScript

import { Support } from '@jangts/agent-core';
import { createDiagnostics } from '@jangts/agent-core/diagnostics';
const scope = Support.createProviderObservationScope({
    accepts: (_owner, descriptor) => descriptor.content === 'metadata',
    write(owner, event, spanId) { console.log(owner.requestId, spanId, event.event); },
});
const provider = new Support.CompatibleModelProvider({
    config: { baseUrl: process.env.MODEL_BASE_URL, apiKey: process.env.MODEL_API_KEY, model: process.env.MODEL_NAME },
    observe: { provider: scope.observer },
});
const diagnostics = scope.attach(createDiagnostics(), { requestId: 'app-request-1' });
console.log(provider, diagnostics.identity?.runId);

Related definitions

• ModelProviderContext
• ProviderEventDescriptor
• ProviderObservation