@tencent-ai/agent-sdk 0.0.1

package/README.md

@@ -0,0 +1,236 @@
+# Genie - Agent SDK
+
+负责与 Agent 交互，提供 Agent SDK 接口。
+
+## 使用
+
+需要注意的是：
+
+- **所有的组件注册都必须在获取组件（容器中的任何一个组件）之前完成，否则注册无效。**
+- **此模块的所有功能都依赖于配置模块 `Product`， 因此在使用时，必须先通过 `registerProductProvider` 去提供配置，才可以正常使用。**
+
+### Product
+
+#### 注册 `ProductProvider`
+
+```ts
+import { Services } from '@tencent-ai/agent-sdk';
+
+class Component {
+    // ...
+
+    async init() {
+        await Services.registerProductProvider(CustomProductProvider);
+        logger.info('hello world');
+    }
+    // ...
+}
+
+class CustomProductProvider {
+    async provide(){
+        return {
+            endpoint: 'your endpoint'
+            // ...
+        }
+    }
+}
+```
+
+#### 获取配置管理组件
+
+```ts
+import { Services } from '@tencent-ai/agent-sdk';
+
+class Component {
+    // ...
+
+    async init() {
+        const productManager = await Services.getProductManager();
+        const productConfiguration = await productManager.waitConfiguration();
+        const logger = await Services.getLogger();
+        logger.info(productConfiguration)
+    }
+    // ...
+}
+```
+
+### Http Request
+
+在整个模块中会共用同一个 `axios` 实例用于 http 请求。
+
+```ts
+import { Services } from '@tencent-ai/agent-sdk';
+
+class Component {
+    // ...
+
+    async init() {
+        const restOperations = await Services.getRestOperations();
+        restOperations.get('path', {});
+    }
+    // ...
+} 
+```
+
+如果需要注册拦截器，方法与 `axios` 一致。
+
+```ts
+import { Services } from '@tencent-ai/agent-sdk';
+
+class Component {
+    // ...
+
+    async init() {
+        const restOperations = await Services.getRestOperations();
+        restOperations.interceptors.request.use(async config => {
+            if (!config.headers) {
+                config.headers = {};
+            }
+            config.headers['X-User-ID'] = 'user-id'
+            return config;
+        });
+    }
+    // ...
+} 
+```
+
+### Logger
+
+```ts
+import { Services } from '@tencent-ai/agent-sdk';
+
+class Component {
+    // ...
+
+    async init() {
+        const logger = await Services.getLogger();
+        logger.info('hello world');
+    }
+    // ...
+} 
+```
+
+这里默认输出到 `console` 控制台，如果需要自定义输出，可以通过 `registerLogger` 注册自定义的 logger。
+
+```ts
+import { Services } from '@tencent-ai/agent-sdk';
+
+class Component {
+    // ...
+    async init() {
+        await Services.registerLogger(CustomLogger);
+        const logger = await Services.getLogger();
+        logger.info('hello world');
+    }
+
+    // ...
+} 
+
+class CustomLogger {
+    // ...
+    info(){
+        // do something
+    }
+    // ...
+}
+```
+
+### Tracing
+
+#### 初始化和使用
+
+```ts
+import { Services } from '@tencent-ai/agent-sdk';
+
+class Component {
+    // ...
+
+    async init() {
+        const traceService = await Services.getTraceService();
+        await traceService.init({serviceName: 'Your-Service-Name'});
+        const trace = traceService.startTrace('login');
+        trace.markAsSuccessful();
+    }
+    // ...
+} 
+```
+
+#### 注册公共信息到 sources
+
+sourcesProvider 提供的信息会作为公共数据绑定到每一个 trace 链路中
+
+```ts
+import { Services } from '@tencent-ai/agent-sdk';
+
+class Component {
+    // ...
+
+    async init() {
+        await Services.registerResourcesProvider(CustomSourcesProvider);
+        const traceService = await Services.getTraceService();
+        await traceService.init({serviceName: 'Your-Service-Name'});
+        const trace = traceService.startTrace('login');
+        trace.markAsSuccessful();
+    }
+    // ...
+} 
+
+class CustomSourcesProvider {
+    async provide() {
+        return {
+            username: '123',
+            userId: '456'
+        }
+    }
+}
+```
+
+### 事件上报
+
+#### 使用
+
+```ts
+import { Services } from '@tencent-ai/agent-sdk';
+
+class Component {
+    // ...
+
+    async init() {
+        const eventService = await Services.getEventService();
+        eventService.Event('your-event-name', { payload: 1 })
+    }
+    // ...
+} 
+```
+
+#### 处理事件公共字段
+
+模块内部会自动收集操作系统相关的信息，作为公共字段。
+如果还需要携带如用户信息，编辑器信息等，需要通过注册处理器实现。
+
+```ts
+import { Services } from '@tencent-ai/agent-sdk';
+
+class Component {
+    // ...
+
+    async init() {
+        await Services.registerEventProcessor(UserInfoEventProcessor);
+        const eventService = await Services.getEventService();
+        eventService.Event('your-event-name', { payload: 1 })
+    }
+    // ...
+} 
+
+class UserInfoEventProcessor {
+    async process({
+        code: string;
+        event: EventPayload;
+    }) {
+        // 这样子所有的事件上报的时候都会带上以下用户信息字段
+        event.username = '张三'；
+        event.userId = '123';
+        event.userNickname = '李四'
+    }
+}
+```