@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.
Files changed (37) hide show
  1. package/CHANGELOG.md +23 -0
  2. package/LICENSE.md +93 -0
  3. package/README.md +162 -0
  4. package/README.zh.md +162 -0
  5. package/lib/cjs/http-client/client.d.ts +97 -0
  6. package/lib/cjs/http-client/client.js +87 -0
  7. package/lib/cjs/http-client/index.d.ts +1 -0
  8. package/lib/cjs/http-client/index.js +17 -0
  9. package/lib/cjs/http-server/error.d.ts +15 -0
  10. package/lib/cjs/http-server/error.js +22 -0
  11. package/lib/cjs/http-server/index.d.ts +2 -0
  12. package/lib/cjs/http-server/index.js +18 -0
  13. package/lib/cjs/http-server/server.d.ts +135 -0
  14. package/lib/cjs/http-server/server.js +187 -0
  15. package/lib/cjs/index.d.ts +1 -0
  16. package/lib/cjs/index.js +2 -0
  17. package/lib/cjs/package.json +1 -0
  18. package/lib/dts/http-client/client.d.ts +97 -0
  19. package/lib/dts/http-client/index.d.ts +1 -0
  20. package/lib/dts/http-server/error.d.ts +15 -0
  21. package/lib/dts/http-server/index.d.ts +2 -0
  22. package/lib/dts/http-server/server.d.ts +135 -0
  23. package/lib/dts/index.d.ts +1 -0
  24. package/lib/esm/http-client/client.d.ts +97 -0
  25. package/lib/esm/http-client/client.js +83 -0
  26. package/lib/esm/http-client/index.d.ts +1 -0
  27. package/lib/esm/http-client/index.js +1 -0
  28. package/lib/esm/http-server/error.d.ts +15 -0
  29. package/lib/esm/http-server/error.js +18 -0
  30. package/lib/esm/http-server/index.d.ts +2 -0
  31. package/lib/esm/http-server/index.js +2 -0
  32. package/lib/esm/http-server/server.d.ts +135 -0
  33. package/lib/esm/http-server/server.js +180 -0
  34. package/lib/esm/index.d.ts +1 -0
  35. package/lib/esm/index.js +1 -0
  36. package/lib/esm/package.json +1 -0
  37. package/package.json +66 -0
@@ -0,0 +1,2 @@
1
+ export * from "./error.js";
2
+ export * from "./server.js";
@@ -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 {};
@@ -0,0 +1,2 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
@@ -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,2 @@
1
+ export * from "./error.js";
2
+ export * from "./server.js";
@@ -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 {};