@aigne/transport 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +23 -0
- package/LICENSE.md +93 -0
- package/README.md +162 -0
- package/README.zh.md +162 -0
- package/lib/cjs/http-client/client.d.ts +97 -0
- package/lib/cjs/http-client/client.js +87 -0
- package/lib/cjs/http-client/index.d.ts +1 -0
- package/lib/cjs/http-client/index.js +17 -0
- package/lib/cjs/http-server/error.d.ts +15 -0
- package/lib/cjs/http-server/error.js +22 -0
- package/lib/cjs/http-server/index.d.ts +2 -0
- package/lib/cjs/http-server/index.js +18 -0
- package/lib/cjs/http-server/server.d.ts +135 -0
- package/lib/cjs/http-server/server.js +187 -0
- package/lib/cjs/index.d.ts +1 -0
- package/lib/cjs/index.js +2 -0
- package/lib/cjs/package.json +1 -0
- package/lib/dts/http-client/client.d.ts +97 -0
- package/lib/dts/http-client/index.d.ts +1 -0
- package/lib/dts/http-server/error.d.ts +15 -0
- package/lib/dts/http-server/index.d.ts +2 -0
- package/lib/dts/http-server/server.d.ts +135 -0
- package/lib/dts/index.d.ts +1 -0
- package/lib/esm/http-client/client.d.ts +97 -0
- package/lib/esm/http-client/client.js +83 -0
- package/lib/esm/http-client/index.d.ts +1 -0
- package/lib/esm/http-client/index.js +1 -0
- package/lib/esm/http-server/error.d.ts +15 -0
- package/lib/esm/http-server/error.js +18 -0
- package/lib/esm/http-server/index.d.ts +2 -0
- package/lib/esm/http-server/index.js +2 -0
- package/lib/esm/http-server/server.d.ts +135 -0
- package/lib/esm/http-server/server.js +180 -0
- package/lib/esm/index.d.ts +1 -0
- package/lib/esm/index.js +1 -0
- package/lib/esm/package.json +1 -0
- package/package.json +66 -0
|
@@ -0,0 +1,18 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
|
|
3
|
+
if (k2 === undefined) k2 = k;
|
|
4
|
+
var desc = Object.getOwnPropertyDescriptor(m, k);
|
|
5
|
+
if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
|
|
6
|
+
desc = { enumerable: true, get: function() { return m[k]; } };
|
|
7
|
+
}
|
|
8
|
+
Object.defineProperty(o, k2, desc);
|
|
9
|
+
}) : (function(o, m, k, k2) {
|
|
10
|
+
if (k2 === undefined) k2 = k;
|
|
11
|
+
o[k2] = m[k];
|
|
12
|
+
}));
|
|
13
|
+
var __exportStar = (this && this.__exportStar) || function(m, exports) {
|
|
14
|
+
for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
|
|
15
|
+
};
|
|
16
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
17
|
+
__exportStar(require("./error.js"), exports);
|
|
18
|
+
__exportStar(require("./server.js"), exports);
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
import { IncomingMessage, ServerResponse } from "node:http";
|
|
2
|
+
import type { AIGNE } from "@aigne/core";
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
/**
|
|
5
|
+
* Schema for validating agent invocation payloads.
|
|
6
|
+
* Defines the expected structure for requests to invoke an agent.
|
|
7
|
+
*
|
|
8
|
+
* @hidden
|
|
9
|
+
*/
|
|
10
|
+
export declare const invokePayloadSchema: z.ZodObject<{
|
|
11
|
+
agent: z.ZodString;
|
|
12
|
+
input: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
|
|
13
|
+
options: z.ZodOptional<z.ZodNullable<z.ZodObject<{
|
|
14
|
+
streaming: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
|
|
15
|
+
}, "strip", z.ZodTypeAny, {
|
|
16
|
+
streaming?: boolean | null | undefined;
|
|
17
|
+
}, {
|
|
18
|
+
streaming?: boolean | null | undefined;
|
|
19
|
+
}>>>;
|
|
20
|
+
}, "strip", z.ZodTypeAny, {
|
|
21
|
+
agent: string;
|
|
22
|
+
input: string | Record<string, unknown>;
|
|
23
|
+
options?: {
|
|
24
|
+
streaming?: boolean | null | undefined;
|
|
25
|
+
} | null | undefined;
|
|
26
|
+
}, {
|
|
27
|
+
agent: string;
|
|
28
|
+
input: string | Record<string, unknown>;
|
|
29
|
+
options?: {
|
|
30
|
+
streaming?: boolean | null | undefined;
|
|
31
|
+
} | null | undefined;
|
|
32
|
+
}>;
|
|
33
|
+
/**
|
|
34
|
+
* Configuration options for the AIGNEHTTPServer.
|
|
35
|
+
* These options control various aspects of server behavior including
|
|
36
|
+
* request parsing, payload limits, and response handling.
|
|
37
|
+
*/
|
|
38
|
+
export interface AIGNEHTTPServerOptions {
|
|
39
|
+
/**
|
|
40
|
+
* Maximum body size for incoming HTTP requests.
|
|
41
|
+
* This controls the upper limit of request payload size when parsing raw HTTP requests.
|
|
42
|
+
* Only used when working with Node.js IncomingMessage objects that don't already have
|
|
43
|
+
* a pre-parsed body property (e.g., when not using Express middleware).
|
|
44
|
+
*
|
|
45
|
+
* @default "4mb"
|
|
46
|
+
*/
|
|
47
|
+
maximumBodySize?: string;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* AIGNEHTTPServer provides HTTP API access to AIGNE capabilities.
|
|
51
|
+
* It handles requests to invoke agents, manages response streaming,
|
|
52
|
+
* and supports multiple HTTP server frameworks including Node.js http,
|
|
53
|
+
* Express, and Fetch API compatible environments.
|
|
54
|
+
*
|
|
55
|
+
* @example
|
|
56
|
+
* Here's a simple example of how to use AIGNEServer with express:
|
|
57
|
+
* {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-express}
|
|
58
|
+
*
|
|
59
|
+
* @example
|
|
60
|
+
* Here's an example of how to use AIGNEServer with Hono:
|
|
61
|
+
* {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-hono}
|
|
62
|
+
*/
|
|
63
|
+
export declare class AIGNEHTTPServer {
|
|
64
|
+
engine: AIGNE;
|
|
65
|
+
options?: AIGNEHTTPServerOptions | undefined;
|
|
66
|
+
/**
|
|
67
|
+
* Creates a new AIGNEServer instance.
|
|
68
|
+
*
|
|
69
|
+
* @param engine - The AIGNE engine instance that will process agent invocations
|
|
70
|
+
* @param options - Configuration options for the server
|
|
71
|
+
*/
|
|
72
|
+
constructor(engine: AIGNE, options?: AIGNEHTTPServerOptions | undefined);
|
|
73
|
+
/**
|
|
74
|
+
* Invokes an agent with the provided input and returns a standard web Response.
|
|
75
|
+
* This method serves as the primary API endpoint for agent invocation.
|
|
76
|
+
*
|
|
77
|
+
* The request can be provided in various formats to support different integration scenarios:
|
|
78
|
+
* - As a pre-parsed JavaScript object
|
|
79
|
+
* - As a Fetch API Request instance (for modern web frameworks)
|
|
80
|
+
* - As a Node.js IncomingMessage (for Express, Fastify, etc.)
|
|
81
|
+
*
|
|
82
|
+
* @param request - The agent invocation request in any supported format
|
|
83
|
+
* @returns A web standard Response object that can be returned directly in frameworks
|
|
84
|
+
* like Hono, Next.js, or any Fetch API compatible environment
|
|
85
|
+
*
|
|
86
|
+
* @example
|
|
87
|
+
* Here's a simple example of how to use AIGNEServer with Hono:
|
|
88
|
+
* {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-hono}
|
|
89
|
+
*/
|
|
90
|
+
invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
|
|
91
|
+
/**
|
|
92
|
+
* Invokes an agent with the provided input and streams the response to a Node.js ServerResponse.
|
|
93
|
+
* This overload is specifically designed for Node.js HTTP server environments.
|
|
94
|
+
*
|
|
95
|
+
* The method handles both regular JSON responses and streaming Server-Sent Events (SSE)
|
|
96
|
+
* responses based on the options specified in the request.
|
|
97
|
+
*
|
|
98
|
+
* @param request - The agent invocation request in any supported format
|
|
99
|
+
* @param response - The Node.js ServerResponse object to write the response to
|
|
100
|
+
*
|
|
101
|
+
* @example
|
|
102
|
+
* Here's a simple example of how to use AIGNEServer with express:
|
|
103
|
+
* {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-express}
|
|
104
|
+
*/
|
|
105
|
+
invoke(request: Record<string, unknown> | Request | IncomingMessage, response: ServerResponse): Promise<void>;
|
|
106
|
+
/**
|
|
107
|
+
* Internal method that handles the core logic of processing an agent invocation request.
|
|
108
|
+
* Validates the request payload, finds the requested agent, and processes the invocation
|
|
109
|
+
* with either streaming or non-streaming response handling.
|
|
110
|
+
*
|
|
111
|
+
* @param request - The parsed or raw request to process
|
|
112
|
+
* @returns A standard Response object with the invocation result
|
|
113
|
+
* @private
|
|
114
|
+
*/
|
|
115
|
+
_invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
|
|
116
|
+
/**
|
|
117
|
+
* Prepares and normalizes the input from various request types.
|
|
118
|
+
* Handles different request formats (Node.js IncomingMessage, Fetch API Request,
|
|
119
|
+
* or already parsed object) and extracts the JSON payload.
|
|
120
|
+
*
|
|
121
|
+
* @param request - The request object in any supported format
|
|
122
|
+
* @returns The normalized payload as a JavaScript object
|
|
123
|
+
* @private
|
|
124
|
+
*/
|
|
125
|
+
_prepareInput(request: Record<string, unknown> | Request | IncomingMessage): Promise<Record<string, unknown>>;
|
|
126
|
+
/**
|
|
127
|
+
* Writes a web standard Response object to a Node.js ServerResponse.
|
|
128
|
+
* Handles streaming responses and error conditions appropriately.
|
|
129
|
+
*
|
|
130
|
+
* @param response - The web standard Response object to write
|
|
131
|
+
* @param res - The Node.js ServerResponse to write to
|
|
132
|
+
* @private
|
|
133
|
+
*/
|
|
134
|
+
_writeResponse(response: Response, res: ServerResponse): Promise<void>;
|
|
135
|
+
}
|
|
@@ -0,0 +1,187 @@
|
|
|
1
|
+
"use strict";
|
|
2
|
+
var __importDefault = (this && this.__importDefault) || function (mod) {
|
|
3
|
+
return (mod && mod.__esModule) ? mod : { "default": mod };
|
|
4
|
+
};
|
|
5
|
+
Object.defineProperty(exports, "__esModule", { value: true });
|
|
6
|
+
exports.AIGNEHTTPServer = exports.invokePayloadSchema = void 0;
|
|
7
|
+
const node_http_1 = require("node:http");
|
|
8
|
+
const event_stream_js_1 = require("@aigne/core/utils/event-stream.js");
|
|
9
|
+
const type_utils_js_1 = require("@aigne/core/utils/type-utils.js");
|
|
10
|
+
const content_type_1 = __importDefault(require("content-type"));
|
|
11
|
+
const raw_body_1 = __importDefault(require("raw-body"));
|
|
12
|
+
const zod_1 = require("zod");
|
|
13
|
+
const error_js_1 = require("./error.js");
|
|
14
|
+
/**
|
|
15
|
+
* Default maximum allowed size for request bodies when parsing raw HTTP requests.
|
|
16
|
+
* This limits the amount of data that can be uploaded to protect against denial of service attacks.
|
|
17
|
+
* Can be overridden via AIGNEServerOptions.
|
|
18
|
+
* @internal
|
|
19
|
+
*/
|
|
20
|
+
const DEFAULT_MAXIMUM_BODY_SIZE = "4mb";
|
|
21
|
+
/**
|
|
22
|
+
* Schema for validating agent invocation payloads.
|
|
23
|
+
* Defines the expected structure for requests to invoke an agent.
|
|
24
|
+
*
|
|
25
|
+
* @hidden
|
|
26
|
+
*/
|
|
27
|
+
exports.invokePayloadSchema = zod_1.z.object({
|
|
28
|
+
agent: zod_1.z.string(),
|
|
29
|
+
input: zod_1.z.union([zod_1.z.string(), zod_1.z.record(zod_1.z.string(), zod_1.z.unknown())]),
|
|
30
|
+
options: zod_1.z
|
|
31
|
+
.object({
|
|
32
|
+
streaming: zod_1.z.boolean().nullish(),
|
|
33
|
+
})
|
|
34
|
+
.nullish(),
|
|
35
|
+
});
|
|
36
|
+
/**
|
|
37
|
+
* AIGNEHTTPServer provides HTTP API access to AIGNE capabilities.
|
|
38
|
+
* It handles requests to invoke agents, manages response streaming,
|
|
39
|
+
* and supports multiple HTTP server frameworks including Node.js http,
|
|
40
|
+
* Express, and Fetch API compatible environments.
|
|
41
|
+
*
|
|
42
|
+
* @example
|
|
43
|
+
* Here's a simple example of how to use AIGNEServer with express:
|
|
44
|
+
* {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-express}
|
|
45
|
+
*
|
|
46
|
+
* @example
|
|
47
|
+
* Here's an example of how to use AIGNEServer with Hono:
|
|
48
|
+
* {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-hono}
|
|
49
|
+
*/
|
|
50
|
+
class AIGNEHTTPServer {
|
|
51
|
+
engine;
|
|
52
|
+
options;
|
|
53
|
+
/**
|
|
54
|
+
* Creates a new AIGNEServer instance.
|
|
55
|
+
*
|
|
56
|
+
* @param engine - The AIGNE engine instance that will process agent invocations
|
|
57
|
+
* @param options - Configuration options for the server
|
|
58
|
+
*/
|
|
59
|
+
constructor(engine, options) {
|
|
60
|
+
this.engine = engine;
|
|
61
|
+
this.options = options;
|
|
62
|
+
}
|
|
63
|
+
async invoke(request, response) {
|
|
64
|
+
const result = await this._invoke(request);
|
|
65
|
+
if (response instanceof node_http_1.ServerResponse) {
|
|
66
|
+
await this._writeResponse(result, response);
|
|
67
|
+
return;
|
|
68
|
+
}
|
|
69
|
+
return result;
|
|
70
|
+
}
|
|
71
|
+
/**
|
|
72
|
+
* Internal method that handles the core logic of processing an agent invocation request.
|
|
73
|
+
* Validates the request payload, finds the requested agent, and processes the invocation
|
|
74
|
+
* with either streaming or non-streaming response handling.
|
|
75
|
+
*
|
|
76
|
+
* @param request - The parsed or raw request to process
|
|
77
|
+
* @returns A standard Response object with the invocation result
|
|
78
|
+
* @private
|
|
79
|
+
*/
|
|
80
|
+
async _invoke(request) {
|
|
81
|
+
const { engine } = this;
|
|
82
|
+
try {
|
|
83
|
+
const payload = await this._prepareInput(request);
|
|
84
|
+
const { agent: agentName, input, options, } = (0, type_utils_js_1.tryOrThrow)(() => (0, type_utils_js_1.checkArguments)(`Invoke agent ${payload.agent}`, exports.invokePayloadSchema, payload), (error) => new error_js_1.ServerError(400, error.message));
|
|
85
|
+
const agent = engine.agents[agentName];
|
|
86
|
+
if (!agent)
|
|
87
|
+
throw new error_js_1.ServerError(404, `Agent ${agentName} not found`);
|
|
88
|
+
if (!options?.streaming) {
|
|
89
|
+
const result = await engine.invoke(agent, input);
|
|
90
|
+
return new Response(JSON.stringify(result), {
|
|
91
|
+
headers: { "Content-Type": "application/json" },
|
|
92
|
+
});
|
|
93
|
+
}
|
|
94
|
+
const stream = await engine.invoke(agent, input, { streaming: true });
|
|
95
|
+
return new Response(new event_stream_js_1.AgentResponseStreamSSE(stream), {
|
|
96
|
+
headers: {
|
|
97
|
+
"Content-Type": "text/event-stream",
|
|
98
|
+
"Cache-Control": "no-cache",
|
|
99
|
+
"X-Accel-Buffering": "no",
|
|
100
|
+
},
|
|
101
|
+
});
|
|
102
|
+
}
|
|
103
|
+
catch (error) {
|
|
104
|
+
return new Response(JSON.stringify({ error: { message: error.message } }), {
|
|
105
|
+
status: error instanceof error_js_1.ServerError ? error.status : 500,
|
|
106
|
+
headers: { "Content-Type": "application/json" },
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* Prepares and normalizes the input from various request types.
|
|
112
|
+
* Handles different request formats (Node.js IncomingMessage, Fetch API Request,
|
|
113
|
+
* or already parsed object) and extracts the JSON payload.
|
|
114
|
+
*
|
|
115
|
+
* @param request - The request object in any supported format
|
|
116
|
+
* @returns The normalized payload as a JavaScript object
|
|
117
|
+
* @private
|
|
118
|
+
*/
|
|
119
|
+
async _prepareInput(request) {
|
|
120
|
+
const contentTypeError = new error_js_1.ServerError(415, "Unsupported Media Type: Content-Type must be application/json");
|
|
121
|
+
if (request instanceof node_http_1.IncomingMessage) {
|
|
122
|
+
// Support for express with json() middleware
|
|
123
|
+
if ("body" in request && typeof request.body === "object") {
|
|
124
|
+
if (!(0, type_utils_js_1.isRecord)(request.body))
|
|
125
|
+
throw contentTypeError;
|
|
126
|
+
return request.body;
|
|
127
|
+
}
|
|
128
|
+
// Support vanilla nodejs http server
|
|
129
|
+
const maximumBodySize = this.options?.maximumBodySize || DEFAULT_MAXIMUM_BODY_SIZE;
|
|
130
|
+
const ct = request.headers["content-type"];
|
|
131
|
+
if (!ct || !ct.includes("application/json"))
|
|
132
|
+
throw contentTypeError;
|
|
133
|
+
const parsedCt = content_type_1.default.parse(ct);
|
|
134
|
+
const raw = await (0, raw_body_1.default)(request, {
|
|
135
|
+
limit: maximumBodySize,
|
|
136
|
+
encoding: parsedCt.parameters.charset ?? "utf-8",
|
|
137
|
+
});
|
|
138
|
+
return (0, type_utils_js_1.tryOrThrow)(() => JSON.parse(raw.toString()), (error) => new error_js_1.ServerError(400, `Parse request body to json error: ${error.message}`));
|
|
139
|
+
}
|
|
140
|
+
if (request instanceof Request) {
|
|
141
|
+
if (!request.headers.get("content-type")?.includes("application/json")) {
|
|
142
|
+
throw contentTypeError;
|
|
143
|
+
}
|
|
144
|
+
return await request.json();
|
|
145
|
+
}
|
|
146
|
+
if (!(0, type_utils_js_1.isRecord)(request))
|
|
147
|
+
throw contentTypeError;
|
|
148
|
+
return request;
|
|
149
|
+
}
|
|
150
|
+
/**
|
|
151
|
+
* Writes a web standard Response object to a Node.js ServerResponse.
|
|
152
|
+
* Handles streaming responses and error conditions appropriately.
|
|
153
|
+
*
|
|
154
|
+
* @param response - The web standard Response object to write
|
|
155
|
+
* @param res - The Node.js ServerResponse to write to
|
|
156
|
+
* @private
|
|
157
|
+
*/
|
|
158
|
+
async _writeResponse(response, res) {
|
|
159
|
+
try {
|
|
160
|
+
res.writeHead(response.status, Object.fromEntries(response.headers.entries()));
|
|
161
|
+
res.flushHeaders();
|
|
162
|
+
if (!response.body)
|
|
163
|
+
throw new Error("Response body is empty");
|
|
164
|
+
for await (const chunk of response.body) {
|
|
165
|
+
res.write(chunk);
|
|
166
|
+
// Support for express with compression middleware
|
|
167
|
+
if ("flush" in res && typeof res.flush === "function") {
|
|
168
|
+
res.flush();
|
|
169
|
+
}
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
catch (error) {
|
|
173
|
+
if (!res.headersSent) {
|
|
174
|
+
res.writeHead(error instanceof error_js_1.ServerError ? error.status : 500, {
|
|
175
|
+
"Content-Type": "application/json",
|
|
176
|
+
});
|
|
177
|
+
}
|
|
178
|
+
if (res.writable) {
|
|
179
|
+
res.write(JSON.stringify({ error: { message: error.message } }));
|
|
180
|
+
}
|
|
181
|
+
}
|
|
182
|
+
finally {
|
|
183
|
+
res.end();
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
}
|
|
187
|
+
exports.AIGNEHTTPServer = AIGNEHTTPServer;
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
package/lib/cjs/index.js
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"type": "commonjs"}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Client module used to interact with the AIGNE framework.
|
|
3
|
+
*/
|
|
4
|
+
import type { AgentInvokeOptions, AgentResponse, AgentResponseStream, Message } from "@aigne/core";
|
|
5
|
+
/**
|
|
6
|
+
* Configuration options for the AIGNEHTTPClient.
|
|
7
|
+
*/
|
|
8
|
+
export interface AIGNEHTTPClientOptions {
|
|
9
|
+
/**
|
|
10
|
+
* The URL of the AIGNE server to connect to.
|
|
11
|
+
* This should point to the base endpoint where the AIGNEServer is hosted.
|
|
12
|
+
*/
|
|
13
|
+
url: string;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Options for invoking an agent through the AIGNEHTTPClient.
|
|
17
|
+
* Extends the standard AgentInvokeOptions with client-specific options.
|
|
18
|
+
*/
|
|
19
|
+
export interface AIGNEHTTPClientInvokeOptions extends AgentInvokeOptions {
|
|
20
|
+
/**
|
|
21
|
+
* Additional fetch API options to customize the HTTP request.
|
|
22
|
+
* These options will be merged with the default options used by the client.
|
|
23
|
+
*/
|
|
24
|
+
fetchOptions?: Partial<RequestInit>;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Http client for interacting with a remote AIGNE server.
|
|
28
|
+
* AIGNEHTTPClient provides a client-side interface that matches the AIGNE API,
|
|
29
|
+
* allowing applications to invoke agents and receive responses from a remote AIGNE instance.
|
|
30
|
+
*
|
|
31
|
+
* @example
|
|
32
|
+
* Here's a simple example of how to use AIGNEClient:
|
|
33
|
+
* {@includeCode ../../test/http-client/http-client.test.ts#example-aigne-client-simple}
|
|
34
|
+
*
|
|
35
|
+
* @example
|
|
36
|
+
* Here's an example of how to use AIGNEClient with streaming response:
|
|
37
|
+
* {@includeCode ../../test/http-client/http-client.test.ts#example-aigne-client-streaming}
|
|
38
|
+
*/
|
|
39
|
+
export declare class AIGNEHTTPClient {
|
|
40
|
+
options: AIGNEHTTPClientOptions;
|
|
41
|
+
/**
|
|
42
|
+
* Creates a new AIGNEClient instance.
|
|
43
|
+
*
|
|
44
|
+
* @param options - Configuration options for connecting to the AIGNE server
|
|
45
|
+
*/
|
|
46
|
+
constructor(options: AIGNEHTTPClientOptions);
|
|
47
|
+
/**
|
|
48
|
+
* Invokes an agent in non-streaming mode and returns the complete response.
|
|
49
|
+
*
|
|
50
|
+
* @param agent - Name of the agent to invoke
|
|
51
|
+
* @param input - Input message for the agent
|
|
52
|
+
* @param options - Options with streaming mode explicitly set to false or omitted
|
|
53
|
+
* @returns The complete agent response
|
|
54
|
+
*
|
|
55
|
+
* @example
|
|
56
|
+
* Here's a simple example of how to use AIGNEClient:
|
|
57
|
+
* {@includeCode ../../test/http-client/http-client.test.ts#example-aigne-client-simple}
|
|
58
|
+
*/
|
|
59
|
+
invoke<I extends Message, O extends Message>(agent: string, input: string | I, options?: AIGNEHTTPClientInvokeOptions & {
|
|
60
|
+
streaming?: false;
|
|
61
|
+
}): Promise<O>;
|
|
62
|
+
/**
|
|
63
|
+
* Invokes an agent with streaming mode enabled and returns a stream of response chunks.
|
|
64
|
+
*
|
|
65
|
+
* @param agent - Name of the agent to invoke
|
|
66
|
+
* @param input - Input message for the agent
|
|
67
|
+
* @param options - Options with streaming mode explicitly set to true
|
|
68
|
+
* @returns A stream of agent response chunks
|
|
69
|
+
*
|
|
70
|
+
* @example
|
|
71
|
+
* Here's an example of how to use AIGNEClient with streaming response:
|
|
72
|
+
* {@includeCode ../../test/http-client/http-client.test.ts#example-aigne-client-streaming}
|
|
73
|
+
*/
|
|
74
|
+
invoke<I extends Message, O extends Message>(agent: string, input: string | I, options: AIGNEHTTPClientInvokeOptions & {
|
|
75
|
+
streaming: true;
|
|
76
|
+
}): Promise<AgentResponseStream<O>>;
|
|
77
|
+
/**
|
|
78
|
+
* Invokes an agent with the given input and options.
|
|
79
|
+
*
|
|
80
|
+
* @param agent - Name of the agent to invoke
|
|
81
|
+
* @param input - Input message for the agent
|
|
82
|
+
* @param options - Options for the invocation
|
|
83
|
+
* @returns Either a complete response or a response stream depending on the streaming option
|
|
84
|
+
*/
|
|
85
|
+
invoke<I extends Message, O extends Message>(agent: string, input: string | I, options?: AIGNEHTTPClientInvokeOptions): Promise<AgentResponse<O>>;
|
|
86
|
+
/**
|
|
87
|
+
* Enhanced fetch method that handles error responses from the AIGNE server.
|
|
88
|
+
* This method wraps the standard fetch API to provide better error handling and reporting.
|
|
89
|
+
*
|
|
90
|
+
* @param args - Standard fetch API arguments (url and options)
|
|
91
|
+
* @returns A Response object if the request was successful
|
|
92
|
+
* @throws Error with detailed information if the request failed
|
|
93
|
+
*
|
|
94
|
+
* @private
|
|
95
|
+
*/
|
|
96
|
+
fetch(...args: Parameters<typeof globalThis.fetch>): Promise<Response>;
|
|
97
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export * from "./client.js";
|
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Custom error class for AIGNEServer HTTP-related errors.
|
|
3
|
+
* Extends the standard Error class with an HTTP status code property.
|
|
4
|
+
* This allows error responses to include appropriate HTTP status codes.
|
|
5
|
+
*/
|
|
6
|
+
export declare class ServerError extends Error {
|
|
7
|
+
status: number;
|
|
8
|
+
/**
|
|
9
|
+
* Creates a new ServerError instance.
|
|
10
|
+
*
|
|
11
|
+
* @param status - The HTTP status code for this error (e.g., 400, 404, 500)
|
|
12
|
+
* @param message - The error message describing what went wrong
|
|
13
|
+
*/
|
|
14
|
+
constructor(status: number, message: string);
|
|
15
|
+
}
|
|
@@ -0,0 +1,135 @@
|
|
|
1
|
+
import { IncomingMessage, ServerResponse } from "node:http";
|
|
2
|
+
import type { AIGNE } from "@aigne/core";
|
|
3
|
+
import { z } from "zod";
|
|
4
|
+
/**
|
|
5
|
+
* Schema for validating agent invocation payloads.
|
|
6
|
+
* Defines the expected structure for requests to invoke an agent.
|
|
7
|
+
*
|
|
8
|
+
* @hidden
|
|
9
|
+
*/
|
|
10
|
+
export declare const invokePayloadSchema: z.ZodObject<{
|
|
11
|
+
agent: z.ZodString;
|
|
12
|
+
input: z.ZodUnion<[z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>]>;
|
|
13
|
+
options: z.ZodOptional<z.ZodNullable<z.ZodObject<{
|
|
14
|
+
streaming: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
|
|
15
|
+
}, "strip", z.ZodTypeAny, {
|
|
16
|
+
streaming?: boolean | null | undefined;
|
|
17
|
+
}, {
|
|
18
|
+
streaming?: boolean | null | undefined;
|
|
19
|
+
}>>>;
|
|
20
|
+
}, "strip", z.ZodTypeAny, {
|
|
21
|
+
agent: string;
|
|
22
|
+
input: string | Record<string, unknown>;
|
|
23
|
+
options?: {
|
|
24
|
+
streaming?: boolean | null | undefined;
|
|
25
|
+
} | null | undefined;
|
|
26
|
+
}, {
|
|
27
|
+
agent: string;
|
|
28
|
+
input: string | Record<string, unknown>;
|
|
29
|
+
options?: {
|
|
30
|
+
streaming?: boolean | null | undefined;
|
|
31
|
+
} | null | undefined;
|
|
32
|
+
}>;
|
|
33
|
+
/**
|
|
34
|
+
* Configuration options for the AIGNEHTTPServer.
|
|
35
|
+
* These options control various aspects of server behavior including
|
|
36
|
+
* request parsing, payload limits, and response handling.
|
|
37
|
+
*/
|
|
38
|
+
export interface AIGNEHTTPServerOptions {
|
|
39
|
+
/**
|
|
40
|
+
* Maximum body size for incoming HTTP requests.
|
|
41
|
+
* This controls the upper limit of request payload size when parsing raw HTTP requests.
|
|
42
|
+
* Only used when working with Node.js IncomingMessage objects that don't already have
|
|
43
|
+
* a pre-parsed body property (e.g., when not using Express middleware).
|
|
44
|
+
*
|
|
45
|
+
* @default "4mb"
|
|
46
|
+
*/
|
|
47
|
+
maximumBodySize?: string;
|
|
48
|
+
}
|
|
49
|
+
/**
|
|
50
|
+
* AIGNEHTTPServer provides HTTP API access to AIGNE capabilities.
|
|
51
|
+
* It handles requests to invoke agents, manages response streaming,
|
|
52
|
+
* and supports multiple HTTP server frameworks including Node.js http,
|
|
53
|
+
* Express, and Fetch API compatible environments.
|
|
54
|
+
*
|
|
55
|
+
* @example
|
|
56
|
+
* Here's a simple example of how to use AIGNEServer with express:
|
|
57
|
+
* {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-express}
|
|
58
|
+
*
|
|
59
|
+
* @example
|
|
60
|
+
* Here's an example of how to use AIGNEServer with Hono:
|
|
61
|
+
* {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-hono}
|
|
62
|
+
*/
|
|
63
|
+
export declare class AIGNEHTTPServer {
|
|
64
|
+
engine: AIGNE;
|
|
65
|
+
options?: AIGNEHTTPServerOptions | undefined;
|
|
66
|
+
/**
|
|
67
|
+
* Creates a new AIGNEServer instance.
|
|
68
|
+
*
|
|
69
|
+
* @param engine - The AIGNE engine instance that will process agent invocations
|
|
70
|
+
* @param options - Configuration options for the server
|
|
71
|
+
*/
|
|
72
|
+
constructor(engine: AIGNE, options?: AIGNEHTTPServerOptions | undefined);
|
|
73
|
+
/**
|
|
74
|
+
* Invokes an agent with the provided input and returns a standard web Response.
|
|
75
|
+
* This method serves as the primary API endpoint for agent invocation.
|
|
76
|
+
*
|
|
77
|
+
* The request can be provided in various formats to support different integration scenarios:
|
|
78
|
+
* - As a pre-parsed JavaScript object
|
|
79
|
+
* - As a Fetch API Request instance (for modern web frameworks)
|
|
80
|
+
* - As a Node.js IncomingMessage (for Express, Fastify, etc.)
|
|
81
|
+
*
|
|
82
|
+
* @param request - The agent invocation request in any supported format
|
|
83
|
+
* @returns A web standard Response object that can be returned directly in frameworks
|
|
84
|
+
* like Hono, Next.js, or any Fetch API compatible environment
|
|
85
|
+
*
|
|
86
|
+
* @example
|
|
87
|
+
* Here's a simple example of how to use AIGNEServer with Hono:
|
|
88
|
+
* {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-hono}
|
|
89
|
+
*/
|
|
90
|
+
invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
|
|
91
|
+
/**
|
|
92
|
+
* Invokes an agent with the provided input and streams the response to a Node.js ServerResponse.
|
|
93
|
+
* This overload is specifically designed for Node.js HTTP server environments.
|
|
94
|
+
*
|
|
95
|
+
* The method handles both regular JSON responses and streaming Server-Sent Events (SSE)
|
|
96
|
+
* responses based on the options specified in the request.
|
|
97
|
+
*
|
|
98
|
+
* @param request - The agent invocation request in any supported format
|
|
99
|
+
* @param response - The Node.js ServerResponse object to write the response to
|
|
100
|
+
*
|
|
101
|
+
* @example
|
|
102
|
+
* Here's a simple example of how to use AIGNEServer with express:
|
|
103
|
+
* {@includeCode ../../test/http-server/http-server.test.ts#example-aigne-server-express}
|
|
104
|
+
*/
|
|
105
|
+
invoke(request: Record<string, unknown> | Request | IncomingMessage, response: ServerResponse): Promise<void>;
|
|
106
|
+
/**
|
|
107
|
+
* Internal method that handles the core logic of processing an agent invocation request.
|
|
108
|
+
* Validates the request payload, finds the requested agent, and processes the invocation
|
|
109
|
+
* with either streaming or non-streaming response handling.
|
|
110
|
+
*
|
|
111
|
+
* @param request - The parsed or raw request to process
|
|
112
|
+
* @returns A standard Response object with the invocation result
|
|
113
|
+
* @private
|
|
114
|
+
*/
|
|
115
|
+
_invoke(request: Record<string, unknown> | Request | IncomingMessage): Promise<Response>;
|
|
116
|
+
/**
|
|
117
|
+
* Prepares and normalizes the input from various request types.
|
|
118
|
+
* Handles different request formats (Node.js IncomingMessage, Fetch API Request,
|
|
119
|
+
* or already parsed object) and extracts the JSON payload.
|
|
120
|
+
*
|
|
121
|
+
* @param request - The request object in any supported format
|
|
122
|
+
* @returns The normalized payload as a JavaScript object
|
|
123
|
+
* @private
|
|
124
|
+
*/
|
|
125
|
+
_prepareInput(request: Record<string, unknown> | Request | IncomingMessage): Promise<Record<string, unknown>>;
|
|
126
|
+
/**
|
|
127
|
+
* Writes a web standard Response object to a Node.js ServerResponse.
|
|
128
|
+
* Handles streaming responses and error conditions appropriately.
|
|
129
|
+
*
|
|
130
|
+
* @param response - The web standard Response object to write
|
|
131
|
+
* @param res - The Node.js ServerResponse to write to
|
|
132
|
+
* @private
|
|
133
|
+
*/
|
|
134
|
+
_writeResponse(response: Response, res: ServerResponse): Promise<void>;
|
|
135
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|