ProviderObserver

SUPPORT · interface · 类型合同

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

导入

TypeScript

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

JavaScript

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

其他公开入口：@jangts/agent-core/types、@jangts/agent-core/structs、@jangts/agent-core/support、@jangts/agent-core/support/model。

定义

interface ProviderObserver

字段结构

字段	类型	必需	说明
accepts	((descriptor: ProviderEventDescriptor, options: Readonly<ModelProviderContext>) => boolean) | undefined	可省略	Returns false to skip an event; absent means accept every event.
write	(event: ProviderObservation, options: Readonly<ModelProviderContext>) => void | Promise<void>	必需	Handles one observation. Throwing or rejecting never affects the provider call.

成员目录

成员	用途
write	Handles one observation. Throwing or rejecting never affects the provider call.

成员详情

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.

参数	类型	传递	说明
event	ProviderObservation	必需	—
options	Readonly<ModelProviderContext>	必需	—

options 的字段

字段	类型	必需	说明
options	Readonly<ModelOptions> | undefined	可省略	只读。Options prepared for this call, including function schemas and JSON mode.
logger	SubFlowLog | undefined	可省略	只读。Explicit optional recorder for this operation; never inferred from diagnostics.
signal	AbortSignal	必需	只读。Non-optional cancellation signal; never undefined once execution has started.
diagnostics	DiagnosticContext | undefined	可省略	只读。Diagnostic scope of the enclosing call, when recording is enabled.

参数 event的可选结构： 选择其中一种结构，各分支的字段要求分别列出。

分支 1

字段	类型	必需	说明
event	"provider.request"	必需	只读。见类型定义及调用场景。
payload	{ url: string; body: unknown; }	必需	只读。见类型定义及调用场景。

分支 2

字段	类型	必需	说明
event	"provider.response"	必需	只读。见类型定义及调用场景。
payload	{ status: number; requestId: string | null; contentType: string | null; }	必需	只读。见类型定义及调用场景。

分支 3

字段	类型	必需	说明
event	"provider.frame"	必需	只读。见类型定义及调用场景。
payload	{ data: string; }	必需	只读。见类型定义及调用场景。

分支 4

字段	类型	必需	说明
event	"provider.error-body"	必需	只读。见类型定义及调用场景。
payload	{ status: number; body: string; truncated?: boolean; }	必需	只读。见类型定义及调用场景。

分支 5

字段	类型	必需	说明
event	"provider.end"	必需	只读。见类型定义及调用场景。
payload	{ complete: boolean; error?: unknown; }	必需	只读。见类型定义及调用场景。

返回： void \| Promise<void>。

等待后的值： void。

使用示例

• Provider 观察与 App 自己的记录目标：稳定 Provider 绑定观察规则，本次请求只关联自己的目标，子作用域继承关联。

只观察元数据

入门 · 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);

按本次请求绑定自己的关联值

配置 · Node.js

此例只装配；实际调用时把该 diagnostics 配入对应请求 execution，不把 App ID 强塞进 Core 身份。

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);

相关定义

• ModelProviderContext
• ProviderEventDescriptor
• ProviderObservation