@mantyx/sdk 0.1.1 → 0.3.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 +19 -1
- package/README.md +213 -14
- package/dist/a2a-server.cjs +404 -0
- package/dist/a2a-server.cjs.map +1 -0
- package/dist/a2a-server.d.cts +170 -0
- package/dist/a2a-server.d.ts +170 -0
- package/dist/a2a-server.js +344 -0
- package/dist/a2a-server.js.map +1 -0
- package/dist/chunk-ZJINVTHD.js +1080 -0
- package/dist/chunk-ZJINVTHD.js.map +1 -0
- package/dist/client-Ce02_fV8.d.cts +591 -0
- package/dist/client-Ce02_fV8.d.ts +591 -0
- package/dist/index.cjs +591 -100
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +3 -261
- package/dist/index.d.ts +3 -261
- package/dist/index.js +30 -587
- package/dist/index.js.map +1 -1
- package/docs/agent-runs-protocol.md +370 -18
- package/package.json +24 -3
package/dist/index.d.cts
CHANGED
|
@@ -1,264 +1,6 @@
|
|
|
1
|
+
export { A as A2AToolRef, a as AgentSession, b as AgentSpecBase, c as AssistantDeltaEvent, d as AssistantMessageEvent, C as CancelledEvent, D as DEFAULT_BASE_URL, e as DefineLocalA2AOptions, f as DefineLocalMcpOptions, g as DefineLocalToolOptions, E as ErrorEvent, L as LocalA2ATool, h as LocalHandlers, i as LocalMcpHttpTransport, j as LocalMcpServer, k as LocalMcpStdioTransport, l as LocalTool, m as LocalToolCallEvent, n as LocalToolResultInEvent, o as MantyxA2AOptions, M as MantyxClient, p as MantyxClientOptions, q as MantyxMcpOptions, r as MantyxPluginToolRef, s as MantyxToolRef, t as McpToolRef, u as ModelCatalog, v as ModelInfo, R as ReasoningLevel, w as ResultEvent, x as RunEvent, y as RunEventBase, z as RunResult, B as RunSpec, S as ServerToolResultEvent, F as SessionInfo, G as SessionSpec, H as ThinkingDeltaEvent, T as ToolRef, Z as ZodLikeObject, I as defineLocalA2A, J as defineLocalMcp, K as defineLocalTool, N as isLocalA2ATool, O as isLocalMcpServer, P as isLocalTool, Q as mantyxA2A, U as mantyxMcp, V as mantyxPluginTool, W as mantyxTool } from './client-Ce02_fV8.cjs';
|
|
1
2
|
import { z } from 'zod';
|
|
2
3
|
|
|
3
|
-
/**
|
|
4
|
-
* Public tool helpers for the MANTYX SDK.
|
|
5
|
-
*
|
|
6
|
-
* defineLocalTool({ name, description, parameters, execute })
|
|
7
|
-
* → A tool that runs in the developer's process. The MANTYX server pauses
|
|
8
|
-
* the agent loop, emits a `local_tool_call` event, and waits for the SDK
|
|
9
|
-
* to POST the result back.
|
|
10
|
-
*
|
|
11
|
-
* mantyxTool(id) → Reference an existing workspace `Tool` row by id.
|
|
12
|
-
* mantyxPluginTool(name) → Reference a built-in plugin tool by `@plugin/tool` name.
|
|
13
|
-
*/
|
|
14
|
-
|
|
15
|
-
type ZodLikeObject = z.ZodType<Record<string, unknown>> & {
|
|
16
|
-
_def?: unknown;
|
|
17
|
-
parse?: (value: unknown) => unknown;
|
|
18
|
-
};
|
|
19
|
-
interface LocalTool<TArgs = Record<string, unknown>> {
|
|
20
|
-
readonly kind: "local";
|
|
21
|
-
readonly name: string;
|
|
22
|
-
readonly description: string;
|
|
23
|
-
readonly parameters: ZodLikeObject | undefined;
|
|
24
|
-
readonly execute: (args: TArgs) => Promise<string> | string;
|
|
25
|
-
}
|
|
26
|
-
interface MantyxToolRef {
|
|
27
|
-
readonly kind: "mantyx";
|
|
28
|
-
readonly id: string;
|
|
29
|
-
}
|
|
30
|
-
interface MantyxPluginToolRef {
|
|
31
|
-
readonly kind: "mantyx_plugin";
|
|
32
|
-
readonly name: string;
|
|
33
|
-
}
|
|
34
|
-
type ToolRef = MantyxToolRef | MantyxPluginToolRef | LocalTool;
|
|
35
|
-
interface DefineLocalToolOptions<T extends ZodLikeObject | undefined> {
|
|
36
|
-
/** Lowercase alphanumeric + underscore, max 64 chars. */
|
|
37
|
-
name: string;
|
|
38
|
-
description?: string;
|
|
39
|
-
parameters?: T;
|
|
40
|
-
execute: (args: T extends ZodLikeObject ? z.infer<T> : Record<string, unknown>) => Promise<string> | string;
|
|
41
|
-
}
|
|
42
|
-
declare function defineLocalTool<T extends ZodLikeObject | undefined>(opts: DefineLocalToolOptions<T>): LocalTool;
|
|
43
|
-
declare function mantyxTool(id: string): MantyxToolRef;
|
|
44
|
-
declare function mantyxPluginTool(name: string): MantyxPluginToolRef;
|
|
45
|
-
declare function isLocalTool(t: ToolRef): t is LocalTool;
|
|
46
|
-
|
|
47
|
-
declare const DEFAULT_BASE_URL = "https://api.mantyx.com";
|
|
48
|
-
interface MantyxClientOptions {
|
|
49
|
-
apiKey: string;
|
|
50
|
-
workspaceSlug: string;
|
|
51
|
-
/** Defaults to `https://api.mantyx.com`. Override for self-hosted instances. */
|
|
52
|
-
baseUrl?: string;
|
|
53
|
-
/** Optional `fetch` override (e.g. node-fetch wrapper, or a custom HTTP client). */
|
|
54
|
-
fetch?: typeof fetch;
|
|
55
|
-
/** Default per-request timeout in milliseconds. Default: 60s. */
|
|
56
|
-
timeoutMs?: number;
|
|
57
|
-
}
|
|
58
|
-
interface ModelInfo {
|
|
59
|
-
id: string;
|
|
60
|
-
label: string;
|
|
61
|
-
provider: string;
|
|
62
|
-
vendorModelId: string;
|
|
63
|
-
source: "workspace_provider" | "platform_offering";
|
|
64
|
-
contextWindowTokens: number | null;
|
|
65
|
-
pricing: {
|
|
66
|
-
inputPer1MUsd: number | null;
|
|
67
|
-
outputPer1MUsd: number | null;
|
|
68
|
-
cacheReadPer1MUsd: number | null;
|
|
69
|
-
} | null;
|
|
70
|
-
}
|
|
71
|
-
interface ModelCatalog {
|
|
72
|
-
models: ModelInfo[];
|
|
73
|
-
defaultModelId: string | null;
|
|
74
|
-
}
|
|
75
|
-
interface AgentSpecBase {
|
|
76
|
-
name?: string;
|
|
77
|
-
/**
|
|
78
|
-
* Reference to a persisted MANTYX agent in this workspace. When set, the
|
|
79
|
-
* server hydrates `systemPrompt`, `modelId`, and the agent's own tools
|
|
80
|
-
* (memory, skills, plugin tools, …) from the Agent row at run time, and any
|
|
81
|
-
* `tools` you supply here are merged on top — typically `local` tools the
|
|
82
|
-
* SDK wants the agent to be able to call back into.
|
|
83
|
-
*
|
|
84
|
-
* Either `agentId` or `systemPrompt` must be set.
|
|
85
|
-
*/
|
|
86
|
-
agentId?: string;
|
|
87
|
-
/** Required unless `agentId` is set. */
|
|
88
|
-
systemPrompt?: string;
|
|
89
|
-
modelId?: string;
|
|
90
|
-
tools?: ToolRef[];
|
|
91
|
-
budgets?: {
|
|
92
|
-
maxToolTurns?: number;
|
|
93
|
-
};
|
|
94
|
-
/**
|
|
95
|
-
* Flat string→string KV carried alongside the run / session for
|
|
96
|
-
* observability. Use it to tag runs with your own application identifiers
|
|
97
|
-
* (customer id, environment, workflow name, …) — the values are visible in
|
|
98
|
-
* the MANTYX dashboard and can be filtered there.
|
|
99
|
-
*
|
|
100
|
-
* Limits enforced server-side: max 16 entries; keys match
|
|
101
|
-
* `[A-Za-z0-9._-]{1,64}`; values are strings ≤ 256 chars; serialized JSON
|
|
102
|
-
* ≤ 4 KB. For session-scoped runs, the session's metadata is inherited and
|
|
103
|
-
* any per-message override is merged on top.
|
|
104
|
-
*/
|
|
105
|
-
metadata?: Record<string, string>;
|
|
106
|
-
}
|
|
107
|
-
interface RunSpec extends AgentSpecBase {
|
|
108
|
-
prompt?: string;
|
|
109
|
-
messages?: Array<{
|
|
110
|
-
role: "user" | "assistant" | "system";
|
|
111
|
-
content: string;
|
|
112
|
-
}>;
|
|
113
|
-
/** Receives streaming assistant text deltas. */
|
|
114
|
-
onAssistantDelta?: (delta: string) => void;
|
|
115
|
-
/** Receives raw events (assistant_message, local_tool_call, tool_result, ...) for advanced consumers. */
|
|
116
|
-
onEvent?: (event: RunEvent) => void;
|
|
117
|
-
/** Aborts the run on the client and best-effort cancels server-side. */
|
|
118
|
-
signal?: AbortSignal;
|
|
119
|
-
}
|
|
120
|
-
type SessionSpec = AgentSpecBase;
|
|
121
|
-
interface RunResult {
|
|
122
|
-
runId: string;
|
|
123
|
-
text: string;
|
|
124
|
-
events: RunEvent[];
|
|
125
|
-
}
|
|
126
|
-
interface RunEventBase {
|
|
127
|
-
seq: number;
|
|
128
|
-
type: string;
|
|
129
|
-
}
|
|
130
|
-
interface AssistantDeltaEvent extends RunEventBase {
|
|
131
|
-
type: "assistant_delta";
|
|
132
|
-
text: string;
|
|
133
|
-
}
|
|
134
|
-
interface ThinkingDeltaEvent extends RunEventBase {
|
|
135
|
-
type: "thinking_delta";
|
|
136
|
-
text: string;
|
|
137
|
-
}
|
|
138
|
-
interface AssistantMessageEvent extends RunEventBase {
|
|
139
|
-
type: "assistant_message";
|
|
140
|
-
text: string;
|
|
141
|
-
}
|
|
142
|
-
interface ServerToolResultEvent extends RunEventBase {
|
|
143
|
-
type: "tool_result";
|
|
144
|
-
name: string;
|
|
145
|
-
args?: Record<string, unknown>;
|
|
146
|
-
ok?: boolean;
|
|
147
|
-
summary?: string;
|
|
148
|
-
phase?: "start" | "end";
|
|
149
|
-
}
|
|
150
|
-
interface LocalToolCallEvent extends RunEventBase {
|
|
151
|
-
type: "local_tool_call";
|
|
152
|
-
toolUseId: string;
|
|
153
|
-
name: string;
|
|
154
|
-
args: Record<string, unknown>;
|
|
155
|
-
}
|
|
156
|
-
interface LocalToolResultInEvent extends RunEventBase {
|
|
157
|
-
type: "local_tool_result_in";
|
|
158
|
-
toolUseId: string;
|
|
159
|
-
result?: string;
|
|
160
|
-
error?: string;
|
|
161
|
-
}
|
|
162
|
-
interface ResultEvent extends RunEventBase {
|
|
163
|
-
type: "result";
|
|
164
|
-
subtype: string;
|
|
165
|
-
text?: string;
|
|
166
|
-
error?: string;
|
|
167
|
-
}
|
|
168
|
-
interface ErrorEvent extends RunEventBase {
|
|
169
|
-
type: "error";
|
|
170
|
-
error: string;
|
|
171
|
-
code?: string;
|
|
172
|
-
}
|
|
173
|
-
interface CancelledEvent extends RunEventBase {
|
|
174
|
-
type: "cancelled";
|
|
175
|
-
reason?: string;
|
|
176
|
-
}
|
|
177
|
-
type RunEvent = AssistantDeltaEvent | ThinkingDeltaEvent | AssistantMessageEvent | ServerToolResultEvent | LocalToolCallEvent | LocalToolResultInEvent | ResultEvent | ErrorEvent | CancelledEvent | (RunEventBase & {
|
|
178
|
-
type: string;
|
|
179
|
-
[key: string]: unknown;
|
|
180
|
-
});
|
|
181
|
-
interface SessionInfo {
|
|
182
|
-
id: string;
|
|
183
|
-
name: string;
|
|
184
|
-
status: "active" | "ended";
|
|
185
|
-
createdAt: string;
|
|
186
|
-
lastUsedAt: string;
|
|
187
|
-
endedAt: string | null;
|
|
188
|
-
agentSpec: AgentSpecBase;
|
|
189
|
-
messages: Array<{
|
|
190
|
-
role: "user" | "assistant" | "system";
|
|
191
|
-
content: string;
|
|
192
|
-
}>;
|
|
193
|
-
/** Metadata that was attached to the session at create time, returned for observability. */
|
|
194
|
-
metadata: Record<string, string>;
|
|
195
|
-
}
|
|
196
|
-
declare class MantyxClient {
|
|
197
|
-
readonly options: Required<Pick<MantyxClientOptions, "apiKey" | "workspaceSlug" | "baseUrl">> & {
|
|
198
|
-
fetch: typeof fetch;
|
|
199
|
-
timeoutMs: number;
|
|
200
|
-
};
|
|
201
|
-
constructor(opts: MantyxClientOptions);
|
|
202
|
-
listModels(): Promise<ModelCatalog>;
|
|
203
|
-
runAgent(spec: RunSpec): Promise<RunResult>;
|
|
204
|
-
streamAgent(spec: RunSpec): AsyncGenerator<RunEvent, void, void>;
|
|
205
|
-
createSession(spec: SessionSpec): Promise<AgentSession>;
|
|
206
|
-
resumeSession(sessionId: string, opts?: {
|
|
207
|
-
tools?: ToolRef[];
|
|
208
|
-
}): Promise<AgentSession>;
|
|
209
|
-
endSession(sessionId: string): Promise<void>;
|
|
210
|
-
getSessionInfo(sessionId: string): Promise<SessionInfo>;
|
|
211
|
-
/** Drive an existing run to completion (collect events, dispatch local tools). */
|
|
212
|
-
driveRun(runId: string, handlers: Map<string, LocalTool>, opts?: {
|
|
213
|
-
onAssistantDelta?: (delta: string) => void;
|
|
214
|
-
onEvent?: (event: RunEvent) => void;
|
|
215
|
-
signal?: AbortSignal;
|
|
216
|
-
}): Promise<RunResult>;
|
|
217
|
-
streamRunEvents(runId: string, handlers: Map<string, LocalTool>, signal?: AbortSignal): AsyncGenerator<RunEvent, void, void>;
|
|
218
|
-
dispatchLocalTool(runId: string, ev: LocalToolCallEvent, handlers: Map<string, LocalTool>): Promise<void>;
|
|
219
|
-
postToolResult(runId: string, toolUseId: string, payload: {
|
|
220
|
-
result?: string;
|
|
221
|
-
error?: string;
|
|
222
|
-
}): Promise<void>;
|
|
223
|
-
cancelRun(runId: string): Promise<void>;
|
|
224
|
-
private absoluteUrl;
|
|
225
|
-
private authHeaders;
|
|
226
|
-
request<T>(args: {
|
|
227
|
-
method: string;
|
|
228
|
-
path: string;
|
|
229
|
-
body?: unknown;
|
|
230
|
-
timeoutMs?: number;
|
|
231
|
-
}): Promise<T>;
|
|
232
|
-
private errorFromResponse;
|
|
233
|
-
}
|
|
234
|
-
declare class AgentSession {
|
|
235
|
-
readonly id: string;
|
|
236
|
-
readonly client: MantyxClient;
|
|
237
|
-
private readonly handlers;
|
|
238
|
-
private readonly toolsForResume;
|
|
239
|
-
constructor(client: MantyxClient, id: string, handlers: Map<string, LocalTool>, toolsForResume?: ToolRef[]);
|
|
240
|
-
send(prompt: string, opts?: {
|
|
241
|
-
onAssistantDelta?: (s: string) => void;
|
|
242
|
-
signal?: AbortSignal;
|
|
243
|
-
/**
|
|
244
|
-
* Per-message metadata override. Server-side this is merged on top of
|
|
245
|
-
* the session's metadata at run-creation time (run-level keys win).
|
|
246
|
-
* Useful for tagging individual turns (e.g. `{ "trace_id": "abc" }`).
|
|
247
|
-
*/
|
|
248
|
-
metadata?: Record<string, string>;
|
|
249
|
-
}): Promise<RunResult>;
|
|
250
|
-
stream(prompt: string, opts?: {
|
|
251
|
-
signal?: AbortSignal;
|
|
252
|
-
metadata?: Record<string, string>;
|
|
253
|
-
}): AsyncGenerator<RunEvent, void, void>;
|
|
254
|
-
history(): Promise<Array<{
|
|
255
|
-
role: "user" | "assistant" | "system";
|
|
256
|
-
content: string;
|
|
257
|
-
}>>;
|
|
258
|
-
info(): Promise<SessionInfo>;
|
|
259
|
-
end(): Promise<void>;
|
|
260
|
-
}
|
|
261
|
-
|
|
262
4
|
/**
|
|
263
5
|
* Error types raised by the MANTYX SDK.
|
|
264
6
|
*/
|
|
@@ -341,6 +83,6 @@ declare function readSseStream(body: ReadableStream<Uint8Array> | null, opts?: S
|
|
|
341
83
|
/**
|
|
342
84
|
* Release version — synced from repo root VERSION (`npm run sync-version`).
|
|
343
85
|
*/
|
|
344
|
-
declare const SDK_VERSION = "0.
|
|
86
|
+
declare const SDK_VERSION = "0.3.0";
|
|
345
87
|
|
|
346
|
-
export {
|
|
88
|
+
export { MantyxAuthError, MantyxError, MantyxNetworkError, MantyxRunError, MantyxToolError, SDK_VERSION, type SseEvent, type SseStreamOptions, readSseStream, toToolParametersWire, zodToJsonSchema };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,264 +1,6 @@
|
|
|
1
|
+
export { A as A2AToolRef, a as AgentSession, b as AgentSpecBase, c as AssistantDeltaEvent, d as AssistantMessageEvent, C as CancelledEvent, D as DEFAULT_BASE_URL, e as DefineLocalA2AOptions, f as DefineLocalMcpOptions, g as DefineLocalToolOptions, E as ErrorEvent, L as LocalA2ATool, h as LocalHandlers, i as LocalMcpHttpTransport, j as LocalMcpServer, k as LocalMcpStdioTransport, l as LocalTool, m as LocalToolCallEvent, n as LocalToolResultInEvent, o as MantyxA2AOptions, M as MantyxClient, p as MantyxClientOptions, q as MantyxMcpOptions, r as MantyxPluginToolRef, s as MantyxToolRef, t as McpToolRef, u as ModelCatalog, v as ModelInfo, R as ReasoningLevel, w as ResultEvent, x as RunEvent, y as RunEventBase, z as RunResult, B as RunSpec, S as ServerToolResultEvent, F as SessionInfo, G as SessionSpec, H as ThinkingDeltaEvent, T as ToolRef, Z as ZodLikeObject, I as defineLocalA2A, J as defineLocalMcp, K as defineLocalTool, N as isLocalA2ATool, O as isLocalMcpServer, P as isLocalTool, Q as mantyxA2A, U as mantyxMcp, V as mantyxPluginTool, W as mantyxTool } from './client-Ce02_fV8.js';
|
|
1
2
|
import { z } from 'zod';
|
|
2
3
|
|
|
3
|
-
/**
|
|
4
|
-
* Public tool helpers for the MANTYX SDK.
|
|
5
|
-
*
|
|
6
|
-
* defineLocalTool({ name, description, parameters, execute })
|
|
7
|
-
* → A tool that runs in the developer's process. The MANTYX server pauses
|
|
8
|
-
* the agent loop, emits a `local_tool_call` event, and waits for the SDK
|
|
9
|
-
* to POST the result back.
|
|
10
|
-
*
|
|
11
|
-
* mantyxTool(id) → Reference an existing workspace `Tool` row by id.
|
|
12
|
-
* mantyxPluginTool(name) → Reference a built-in plugin tool by `@plugin/tool` name.
|
|
13
|
-
*/
|
|
14
|
-
|
|
15
|
-
type ZodLikeObject = z.ZodType<Record<string, unknown>> & {
|
|
16
|
-
_def?: unknown;
|
|
17
|
-
parse?: (value: unknown) => unknown;
|
|
18
|
-
};
|
|
19
|
-
interface LocalTool<TArgs = Record<string, unknown>> {
|
|
20
|
-
readonly kind: "local";
|
|
21
|
-
readonly name: string;
|
|
22
|
-
readonly description: string;
|
|
23
|
-
readonly parameters: ZodLikeObject | undefined;
|
|
24
|
-
readonly execute: (args: TArgs) => Promise<string> | string;
|
|
25
|
-
}
|
|
26
|
-
interface MantyxToolRef {
|
|
27
|
-
readonly kind: "mantyx";
|
|
28
|
-
readonly id: string;
|
|
29
|
-
}
|
|
30
|
-
interface MantyxPluginToolRef {
|
|
31
|
-
readonly kind: "mantyx_plugin";
|
|
32
|
-
readonly name: string;
|
|
33
|
-
}
|
|
34
|
-
type ToolRef = MantyxToolRef | MantyxPluginToolRef | LocalTool;
|
|
35
|
-
interface DefineLocalToolOptions<T extends ZodLikeObject | undefined> {
|
|
36
|
-
/** Lowercase alphanumeric + underscore, max 64 chars. */
|
|
37
|
-
name: string;
|
|
38
|
-
description?: string;
|
|
39
|
-
parameters?: T;
|
|
40
|
-
execute: (args: T extends ZodLikeObject ? z.infer<T> : Record<string, unknown>) => Promise<string> | string;
|
|
41
|
-
}
|
|
42
|
-
declare function defineLocalTool<T extends ZodLikeObject | undefined>(opts: DefineLocalToolOptions<T>): LocalTool;
|
|
43
|
-
declare function mantyxTool(id: string): MantyxToolRef;
|
|
44
|
-
declare function mantyxPluginTool(name: string): MantyxPluginToolRef;
|
|
45
|
-
declare function isLocalTool(t: ToolRef): t is LocalTool;
|
|
46
|
-
|
|
47
|
-
declare const DEFAULT_BASE_URL = "https://api.mantyx.com";
|
|
48
|
-
interface MantyxClientOptions {
|
|
49
|
-
apiKey: string;
|
|
50
|
-
workspaceSlug: string;
|
|
51
|
-
/** Defaults to `https://api.mantyx.com`. Override for self-hosted instances. */
|
|
52
|
-
baseUrl?: string;
|
|
53
|
-
/** Optional `fetch` override (e.g. node-fetch wrapper, or a custom HTTP client). */
|
|
54
|
-
fetch?: typeof fetch;
|
|
55
|
-
/** Default per-request timeout in milliseconds. Default: 60s. */
|
|
56
|
-
timeoutMs?: number;
|
|
57
|
-
}
|
|
58
|
-
interface ModelInfo {
|
|
59
|
-
id: string;
|
|
60
|
-
label: string;
|
|
61
|
-
provider: string;
|
|
62
|
-
vendorModelId: string;
|
|
63
|
-
source: "workspace_provider" | "platform_offering";
|
|
64
|
-
contextWindowTokens: number | null;
|
|
65
|
-
pricing: {
|
|
66
|
-
inputPer1MUsd: number | null;
|
|
67
|
-
outputPer1MUsd: number | null;
|
|
68
|
-
cacheReadPer1MUsd: number | null;
|
|
69
|
-
} | null;
|
|
70
|
-
}
|
|
71
|
-
interface ModelCatalog {
|
|
72
|
-
models: ModelInfo[];
|
|
73
|
-
defaultModelId: string | null;
|
|
74
|
-
}
|
|
75
|
-
interface AgentSpecBase {
|
|
76
|
-
name?: string;
|
|
77
|
-
/**
|
|
78
|
-
* Reference to a persisted MANTYX agent in this workspace. When set, the
|
|
79
|
-
* server hydrates `systemPrompt`, `modelId`, and the agent's own tools
|
|
80
|
-
* (memory, skills, plugin tools, …) from the Agent row at run time, and any
|
|
81
|
-
* `tools` you supply here are merged on top — typically `local` tools the
|
|
82
|
-
* SDK wants the agent to be able to call back into.
|
|
83
|
-
*
|
|
84
|
-
* Either `agentId` or `systemPrompt` must be set.
|
|
85
|
-
*/
|
|
86
|
-
agentId?: string;
|
|
87
|
-
/** Required unless `agentId` is set. */
|
|
88
|
-
systemPrompt?: string;
|
|
89
|
-
modelId?: string;
|
|
90
|
-
tools?: ToolRef[];
|
|
91
|
-
budgets?: {
|
|
92
|
-
maxToolTurns?: number;
|
|
93
|
-
};
|
|
94
|
-
/**
|
|
95
|
-
* Flat string→string KV carried alongside the run / session for
|
|
96
|
-
* observability. Use it to tag runs with your own application identifiers
|
|
97
|
-
* (customer id, environment, workflow name, …) — the values are visible in
|
|
98
|
-
* the MANTYX dashboard and can be filtered there.
|
|
99
|
-
*
|
|
100
|
-
* Limits enforced server-side: max 16 entries; keys match
|
|
101
|
-
* `[A-Za-z0-9._-]{1,64}`; values are strings ≤ 256 chars; serialized JSON
|
|
102
|
-
* ≤ 4 KB. For session-scoped runs, the session's metadata is inherited and
|
|
103
|
-
* any per-message override is merged on top.
|
|
104
|
-
*/
|
|
105
|
-
metadata?: Record<string, string>;
|
|
106
|
-
}
|
|
107
|
-
interface RunSpec extends AgentSpecBase {
|
|
108
|
-
prompt?: string;
|
|
109
|
-
messages?: Array<{
|
|
110
|
-
role: "user" | "assistant" | "system";
|
|
111
|
-
content: string;
|
|
112
|
-
}>;
|
|
113
|
-
/** Receives streaming assistant text deltas. */
|
|
114
|
-
onAssistantDelta?: (delta: string) => void;
|
|
115
|
-
/** Receives raw events (assistant_message, local_tool_call, tool_result, ...) for advanced consumers. */
|
|
116
|
-
onEvent?: (event: RunEvent) => void;
|
|
117
|
-
/** Aborts the run on the client and best-effort cancels server-side. */
|
|
118
|
-
signal?: AbortSignal;
|
|
119
|
-
}
|
|
120
|
-
type SessionSpec = AgentSpecBase;
|
|
121
|
-
interface RunResult {
|
|
122
|
-
runId: string;
|
|
123
|
-
text: string;
|
|
124
|
-
events: RunEvent[];
|
|
125
|
-
}
|
|
126
|
-
interface RunEventBase {
|
|
127
|
-
seq: number;
|
|
128
|
-
type: string;
|
|
129
|
-
}
|
|
130
|
-
interface AssistantDeltaEvent extends RunEventBase {
|
|
131
|
-
type: "assistant_delta";
|
|
132
|
-
text: string;
|
|
133
|
-
}
|
|
134
|
-
interface ThinkingDeltaEvent extends RunEventBase {
|
|
135
|
-
type: "thinking_delta";
|
|
136
|
-
text: string;
|
|
137
|
-
}
|
|
138
|
-
interface AssistantMessageEvent extends RunEventBase {
|
|
139
|
-
type: "assistant_message";
|
|
140
|
-
text: string;
|
|
141
|
-
}
|
|
142
|
-
interface ServerToolResultEvent extends RunEventBase {
|
|
143
|
-
type: "tool_result";
|
|
144
|
-
name: string;
|
|
145
|
-
args?: Record<string, unknown>;
|
|
146
|
-
ok?: boolean;
|
|
147
|
-
summary?: string;
|
|
148
|
-
phase?: "start" | "end";
|
|
149
|
-
}
|
|
150
|
-
interface LocalToolCallEvent extends RunEventBase {
|
|
151
|
-
type: "local_tool_call";
|
|
152
|
-
toolUseId: string;
|
|
153
|
-
name: string;
|
|
154
|
-
args: Record<string, unknown>;
|
|
155
|
-
}
|
|
156
|
-
interface LocalToolResultInEvent extends RunEventBase {
|
|
157
|
-
type: "local_tool_result_in";
|
|
158
|
-
toolUseId: string;
|
|
159
|
-
result?: string;
|
|
160
|
-
error?: string;
|
|
161
|
-
}
|
|
162
|
-
interface ResultEvent extends RunEventBase {
|
|
163
|
-
type: "result";
|
|
164
|
-
subtype: string;
|
|
165
|
-
text?: string;
|
|
166
|
-
error?: string;
|
|
167
|
-
}
|
|
168
|
-
interface ErrorEvent extends RunEventBase {
|
|
169
|
-
type: "error";
|
|
170
|
-
error: string;
|
|
171
|
-
code?: string;
|
|
172
|
-
}
|
|
173
|
-
interface CancelledEvent extends RunEventBase {
|
|
174
|
-
type: "cancelled";
|
|
175
|
-
reason?: string;
|
|
176
|
-
}
|
|
177
|
-
type RunEvent = AssistantDeltaEvent | ThinkingDeltaEvent | AssistantMessageEvent | ServerToolResultEvent | LocalToolCallEvent | LocalToolResultInEvent | ResultEvent | ErrorEvent | CancelledEvent | (RunEventBase & {
|
|
178
|
-
type: string;
|
|
179
|
-
[key: string]: unknown;
|
|
180
|
-
});
|
|
181
|
-
interface SessionInfo {
|
|
182
|
-
id: string;
|
|
183
|
-
name: string;
|
|
184
|
-
status: "active" | "ended";
|
|
185
|
-
createdAt: string;
|
|
186
|
-
lastUsedAt: string;
|
|
187
|
-
endedAt: string | null;
|
|
188
|
-
agentSpec: AgentSpecBase;
|
|
189
|
-
messages: Array<{
|
|
190
|
-
role: "user" | "assistant" | "system";
|
|
191
|
-
content: string;
|
|
192
|
-
}>;
|
|
193
|
-
/** Metadata that was attached to the session at create time, returned for observability. */
|
|
194
|
-
metadata: Record<string, string>;
|
|
195
|
-
}
|
|
196
|
-
declare class MantyxClient {
|
|
197
|
-
readonly options: Required<Pick<MantyxClientOptions, "apiKey" | "workspaceSlug" | "baseUrl">> & {
|
|
198
|
-
fetch: typeof fetch;
|
|
199
|
-
timeoutMs: number;
|
|
200
|
-
};
|
|
201
|
-
constructor(opts: MantyxClientOptions);
|
|
202
|
-
listModels(): Promise<ModelCatalog>;
|
|
203
|
-
runAgent(spec: RunSpec): Promise<RunResult>;
|
|
204
|
-
streamAgent(spec: RunSpec): AsyncGenerator<RunEvent, void, void>;
|
|
205
|
-
createSession(spec: SessionSpec): Promise<AgentSession>;
|
|
206
|
-
resumeSession(sessionId: string, opts?: {
|
|
207
|
-
tools?: ToolRef[];
|
|
208
|
-
}): Promise<AgentSession>;
|
|
209
|
-
endSession(sessionId: string): Promise<void>;
|
|
210
|
-
getSessionInfo(sessionId: string): Promise<SessionInfo>;
|
|
211
|
-
/** Drive an existing run to completion (collect events, dispatch local tools). */
|
|
212
|
-
driveRun(runId: string, handlers: Map<string, LocalTool>, opts?: {
|
|
213
|
-
onAssistantDelta?: (delta: string) => void;
|
|
214
|
-
onEvent?: (event: RunEvent) => void;
|
|
215
|
-
signal?: AbortSignal;
|
|
216
|
-
}): Promise<RunResult>;
|
|
217
|
-
streamRunEvents(runId: string, handlers: Map<string, LocalTool>, signal?: AbortSignal): AsyncGenerator<RunEvent, void, void>;
|
|
218
|
-
dispatchLocalTool(runId: string, ev: LocalToolCallEvent, handlers: Map<string, LocalTool>): Promise<void>;
|
|
219
|
-
postToolResult(runId: string, toolUseId: string, payload: {
|
|
220
|
-
result?: string;
|
|
221
|
-
error?: string;
|
|
222
|
-
}): Promise<void>;
|
|
223
|
-
cancelRun(runId: string): Promise<void>;
|
|
224
|
-
private absoluteUrl;
|
|
225
|
-
private authHeaders;
|
|
226
|
-
request<T>(args: {
|
|
227
|
-
method: string;
|
|
228
|
-
path: string;
|
|
229
|
-
body?: unknown;
|
|
230
|
-
timeoutMs?: number;
|
|
231
|
-
}): Promise<T>;
|
|
232
|
-
private errorFromResponse;
|
|
233
|
-
}
|
|
234
|
-
declare class AgentSession {
|
|
235
|
-
readonly id: string;
|
|
236
|
-
readonly client: MantyxClient;
|
|
237
|
-
private readonly handlers;
|
|
238
|
-
private readonly toolsForResume;
|
|
239
|
-
constructor(client: MantyxClient, id: string, handlers: Map<string, LocalTool>, toolsForResume?: ToolRef[]);
|
|
240
|
-
send(prompt: string, opts?: {
|
|
241
|
-
onAssistantDelta?: (s: string) => void;
|
|
242
|
-
signal?: AbortSignal;
|
|
243
|
-
/**
|
|
244
|
-
* Per-message metadata override. Server-side this is merged on top of
|
|
245
|
-
* the session's metadata at run-creation time (run-level keys win).
|
|
246
|
-
* Useful for tagging individual turns (e.g. `{ "trace_id": "abc" }`).
|
|
247
|
-
*/
|
|
248
|
-
metadata?: Record<string, string>;
|
|
249
|
-
}): Promise<RunResult>;
|
|
250
|
-
stream(prompt: string, opts?: {
|
|
251
|
-
signal?: AbortSignal;
|
|
252
|
-
metadata?: Record<string, string>;
|
|
253
|
-
}): AsyncGenerator<RunEvent, void, void>;
|
|
254
|
-
history(): Promise<Array<{
|
|
255
|
-
role: "user" | "assistant" | "system";
|
|
256
|
-
content: string;
|
|
257
|
-
}>>;
|
|
258
|
-
info(): Promise<SessionInfo>;
|
|
259
|
-
end(): Promise<void>;
|
|
260
|
-
}
|
|
261
|
-
|
|
262
4
|
/**
|
|
263
5
|
* Error types raised by the MANTYX SDK.
|
|
264
6
|
*/
|
|
@@ -341,6 +83,6 @@ declare function readSseStream(body: ReadableStream<Uint8Array> | null, opts?: S
|
|
|
341
83
|
/**
|
|
342
84
|
* Release version — synced from repo root VERSION (`npm run sync-version`).
|
|
343
85
|
*/
|
|
344
|
-
declare const SDK_VERSION = "0.
|
|
86
|
+
declare const SDK_VERSION = "0.3.0";
|
|
345
87
|
|
|
346
|
-
export {
|
|
88
|
+
export { MantyxAuthError, MantyxError, MantyxNetworkError, MantyxRunError, MantyxToolError, SDK_VERSION, type SseEvent, type SseStreamOptions, readSseStream, toToolParametersWire, zodToJsonSchema };
|