@openserv-labs/sdk 2.3.0 → 2.4.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/README.md +110 -22
- package/dist/agent.d.ts +94 -41
- package/dist/agent.d.ts.map +1 -1
- package/dist/agent.js +141 -35
- package/dist/capability.d.ts +5 -2
- package/dist/capability.d.ts.map +1 -1
- package/dist/capability.js +8 -3
- package/dist/dreamkid/arcs.d.ts +6 -0
- package/dist/dreamkid/arcs.d.ts.map +1 -0
- package/dist/dreamkid/arcs.js +248 -0
- package/dist/dreamkid/elevenlabs.d.ts +3 -0
- package/dist/dreamkid/elevenlabs.d.ts.map +1 -0
- package/dist/dreamkid/elevenlabs.js +7 -0
- package/dist/dreamkid/main.d.ts +2 -0
- package/dist/dreamkid/main.d.ts.map +1 -0
- package/dist/dreamkid/main.js +313 -0
- package/dist/dreamkid/openai.d.ts +4 -0
- package/dist/dreamkid/openai.d.ts.map +1 -0
- package/dist/dreamkid/openai.js +10 -0
- package/dist/dreamkid/prompting.d.ts +16 -0
- package/dist/dreamkid/prompting.d.ts.map +1 -0
- package/dist/dreamkid/prompting.js +86 -0
- package/dist/dreamkid/system-prompt.d.ts +2 -0
- package/dist/dreamkid/system-prompt.d.ts.map +1 -0
- package/dist/dreamkid/system-prompt.js +14 -0
- package/dist/dreamkid/themes.d.ts +15 -0
- package/dist/dreamkid/themes.d.ts.map +1 -0
- package/dist/dreamkid/themes.js +1255 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/run.d.ts +1 -1
- package/dist/run.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -232,7 +232,7 @@ npm install @openserv-labs/sdk
|
|
|
232
232
|
agent.addCapability({
|
|
233
233
|
name: 'greet',
|
|
234
234
|
description: 'Greet a user by name',
|
|
235
|
-
|
|
235
|
+
inputSchema: z.object({
|
|
236
236
|
name: z.string().describe('The name of the user to greet')
|
|
237
237
|
}),
|
|
238
238
|
async run({ args }) {
|
|
@@ -273,7 +273,7 @@ const agent = new Agent({
|
|
|
273
273
|
agent.addCapability({
|
|
274
274
|
name: 'greet',
|
|
275
275
|
description: 'Greet a user by name',
|
|
276
|
-
|
|
276
|
+
inputSchema: z.object({
|
|
277
277
|
name: z.string().describe('The name of the user to greet')
|
|
278
278
|
}),
|
|
279
279
|
async run({ args }) {
|
|
@@ -286,7 +286,7 @@ agent.addCapabilities([
|
|
|
286
286
|
{
|
|
287
287
|
name: 'farewell',
|
|
288
288
|
description: 'Say goodbye to a user',
|
|
289
|
-
|
|
289
|
+
inputSchema: z.object({
|
|
290
290
|
name: z.string().describe('The name of the user to bid farewell')
|
|
291
291
|
}),
|
|
292
292
|
async run({ args }) {
|
|
@@ -296,7 +296,7 @@ agent.addCapabilities([
|
|
|
296
296
|
{
|
|
297
297
|
name: 'help',
|
|
298
298
|
description: 'Show available commands',
|
|
299
|
-
|
|
299
|
+
inputSchema: z.object({}),
|
|
300
300
|
async run() {
|
|
301
301
|
return 'Available commands: greet, farewell, help'
|
|
302
302
|
}
|
|
@@ -316,13 +316,13 @@ agent.start()
|
|
|
316
316
|
| Variable | Description | Required | Default |
|
|
317
317
|
| --------------------- | ------------------------------------------ | -------- | ---------------------------------- |
|
|
318
318
|
| `OPENSERV_API_KEY` | Your OpenServ API key | Yes | - |
|
|
319
|
-
| `OPENAI_API_KEY` | OpenAI API key (for process() method)
|
|
319
|
+
| `OPENAI_API_KEY` | OpenAI API key (only for process() method) | No | - |
|
|
320
320
|
| `PORT` | Server port | No | 7378 |
|
|
321
321
|
| `OPENSERV_AUTH_TOKEN` | Token for authenticating incoming requests | No | - |
|
|
322
322
|
| `OPENSERV_PROXY_URL` | Custom proxy URL for tunnel connections | No | `https://agents-proxy.openserv.ai` |
|
|
323
323
|
| `DISABLE_TUNNEL` | Skip tunnel and run HTTP server only | No | - |
|
|
324
324
|
|
|
325
|
-
|
|
325
|
+
**Note:** `OPENAI_API_KEY` is only needed if you use the `process()` method for direct OpenAI calls. Most agents don't need it -- use run-less capabilities or `generate()` instead.
|
|
326
326
|
|
|
327
327
|
## Core Concepts
|
|
328
328
|
|
|
@@ -334,8 +334,10 @@ Each capability must include:
|
|
|
334
334
|
|
|
335
335
|
- `name`: Unique identifier for the capability
|
|
336
336
|
- `description`: What the capability does
|
|
337
|
-
- `
|
|
338
|
-
- `run`: Function that executes the capability
|
|
337
|
+
- `inputSchema`: Zod schema defining the input parameters (optional for run-less capabilities, defaults to `z.object({ input: z.string() })`)
|
|
338
|
+
- `run`: Function that executes the capability (optional -- omit for run-less capabilities handled by the runtime)
|
|
339
|
+
- `outputSchema`: Zod schema for structured LLM output (only for run-less capabilities)
|
|
340
|
+
- `schema`: **Deprecated** -- use `inputSchema` instead (kept for backwards compatibility)
|
|
339
341
|
|
|
340
342
|
```typescript
|
|
341
343
|
import { Agent } from '@openserv-labs/sdk'
|
|
@@ -349,7 +351,7 @@ const agent = new Agent({
|
|
|
349
351
|
agent.addCapability({
|
|
350
352
|
name: 'summarize',
|
|
351
353
|
description: 'Summarize a piece of text',
|
|
352
|
-
|
|
354
|
+
inputSchema: z.object({
|
|
353
355
|
text: z.string().describe('Text content to summarize'),
|
|
354
356
|
maxLength: z.number().optional().describe('Maximum length of summary')
|
|
355
357
|
}),
|
|
@@ -377,7 +379,7 @@ agent.addCapabilities([
|
|
|
377
379
|
{
|
|
378
380
|
name: 'analyze',
|
|
379
381
|
description: 'Analyze text for sentiment and keywords',
|
|
380
|
-
|
|
382
|
+
inputSchema: z.object({
|
|
381
383
|
text: z.string().describe('Text to analyze')
|
|
382
384
|
}),
|
|
383
385
|
async run({ args, action }) {
|
|
@@ -388,7 +390,7 @@ agent.addCapabilities([
|
|
|
388
390
|
{
|
|
389
391
|
name: 'help',
|
|
390
392
|
description: 'Show available commands',
|
|
391
|
-
|
|
393
|
+
inputSchema: z.object({}),
|
|
392
394
|
async run({ args, action }) {
|
|
393
395
|
return 'Available commands: summarize, analyze, help'
|
|
394
396
|
}
|
|
@@ -399,8 +401,8 @@ agent.addCapabilities([
|
|
|
399
401
|
Each capability's run function receives:
|
|
400
402
|
|
|
401
403
|
- `params`: Object containing:
|
|
402
|
-
- `args`: The validated arguments matching the capability's
|
|
403
|
-
- `action`: The action context containing:
|
|
404
|
+
- `args`: The validated arguments matching the capability's inputSchema
|
|
405
|
+
- `action`: The action context provided by the runtime, containing:
|
|
404
406
|
- `task`: The current task context (if running as part of a task)
|
|
405
407
|
- `workspace`: The current workspace context
|
|
406
408
|
- `me`: Information about the current agent
|
|
@@ -408,6 +410,92 @@ Each capability's run function receives:
|
|
|
408
410
|
|
|
409
411
|
The run function must return a string or Promise<string>.
|
|
410
412
|
|
|
413
|
+
### Run-less Capabilities
|
|
414
|
+
|
|
415
|
+
Run-less capabilities let you define tools without a `run` function. The OpenServ runtime handles execution via its own LLM, using the capability's `description` as instructions. This means you don't need your own OpenAI key.
|
|
416
|
+
|
|
417
|
+
```typescript
|
|
418
|
+
import { Agent, run } from '@openserv-labs/sdk'
|
|
419
|
+
import { z } from 'zod'
|
|
420
|
+
|
|
421
|
+
const agent = new Agent({
|
|
422
|
+
systemPrompt: 'You are a creative writing assistant.'
|
|
423
|
+
})
|
|
424
|
+
|
|
425
|
+
// Simplest form: just name + description (default inputSchema: { input: string })
|
|
426
|
+
agent.addCapability({
|
|
427
|
+
name: 'generate_haiku',
|
|
428
|
+
description:
|
|
429
|
+
'Generate a haiku poem (5-7-5 syllables) about the given input. Only output the haiku.'
|
|
430
|
+
})
|
|
431
|
+
|
|
432
|
+
// With custom inputSchema
|
|
433
|
+
agent.addCapability({
|
|
434
|
+
name: 'translate',
|
|
435
|
+
description: 'Translate the given text to the target language. Return only the translated text.',
|
|
436
|
+
inputSchema: z.object({
|
|
437
|
+
text: z.string().describe('The text to translate'),
|
|
438
|
+
targetLanguage: z.string().describe('The target language')
|
|
439
|
+
})
|
|
440
|
+
})
|
|
441
|
+
|
|
442
|
+
// With structured output via outputSchema
|
|
443
|
+
agent.addCapability({
|
|
444
|
+
name: 'analyze_sentiment',
|
|
445
|
+
description: 'Analyze the sentiment of the given input text.',
|
|
446
|
+
outputSchema: z.object({
|
|
447
|
+
sentiment: z.enum(['positive', 'negative', 'neutral']),
|
|
448
|
+
confidence: z.number().min(0).max(1)
|
|
449
|
+
})
|
|
450
|
+
})
|
|
451
|
+
|
|
452
|
+
run(agent)
|
|
453
|
+
```
|
|
454
|
+
|
|
455
|
+
### The `generate()` Method
|
|
456
|
+
|
|
457
|
+
Inside custom `run` functions, use `this.generate()` to delegate LLM calls to the OpenServ runtime without needing your own OpenAI key. The `action` parameter is required for billing. You can optionally pass `messages` for conversation context.
|
|
458
|
+
|
|
459
|
+
```typescript
|
|
460
|
+
agent.addCapability({
|
|
461
|
+
name: 'write_and_save_poem',
|
|
462
|
+
description: 'Write a poem and save it to the workspace',
|
|
463
|
+
inputSchema: z.object({ topic: z.string() }),
|
|
464
|
+
async run({ args, action }, messages) {
|
|
465
|
+
// Text generation
|
|
466
|
+
const poem = await this.generate({
|
|
467
|
+
prompt: `Write a short poem about ${args.topic}`,
|
|
468
|
+
action
|
|
469
|
+
})
|
|
470
|
+
|
|
471
|
+
// Structured output generation
|
|
472
|
+
const metadata = await this.generate({
|
|
473
|
+
prompt: `Suggest a title and 3 tags for this poem: ${poem}`,
|
|
474
|
+
outputSchema: z.object({
|
|
475
|
+
title: z.string(),
|
|
476
|
+
tags: z.array(z.string()).length(3)
|
|
477
|
+
}),
|
|
478
|
+
action
|
|
479
|
+
})
|
|
480
|
+
|
|
481
|
+
// With conversation history for context
|
|
482
|
+
const followUp = await this.generate({
|
|
483
|
+
prompt: 'Based on our conversation, suggest a related topic.',
|
|
484
|
+
messages, // pass conversation history from the run function
|
|
485
|
+
action
|
|
486
|
+
})
|
|
487
|
+
|
|
488
|
+
await this.uploadFile({
|
|
489
|
+
workspaceId: action.workspace.id,
|
|
490
|
+
path: `poems/${metadata.title}.txt`,
|
|
491
|
+
file: poem
|
|
492
|
+
})
|
|
493
|
+
|
|
494
|
+
return `Saved "${metadata.title}" with tags: ${metadata.tags.join(', ')}`
|
|
495
|
+
}
|
|
496
|
+
})
|
|
497
|
+
```
|
|
498
|
+
|
|
411
499
|
### Tasks
|
|
412
500
|
|
|
413
501
|
Tasks are units of work that agents can execute. They can have dependencies, require human assistance, and maintain state:
|
|
@@ -451,7 +539,7 @@ const customerSupportAgent = new Agent({
|
|
|
451
539
|
{
|
|
452
540
|
name: 'respondToCustomer',
|
|
453
541
|
description: 'Generate a response to a customer inquiry',
|
|
454
|
-
|
|
542
|
+
inputSchema: z.object({
|
|
455
543
|
query: z.string(),
|
|
456
544
|
context: z.string().optional()
|
|
457
545
|
}),
|
|
@@ -771,7 +859,7 @@ const agent = new Agent({
|
|
|
771
859
|
agent.addCapability({
|
|
772
860
|
name: 'greet',
|
|
773
861
|
description: 'Greet someone',
|
|
774
|
-
|
|
862
|
+
inputSchema: z.object({ name: z.string() }),
|
|
775
863
|
async run({ args }) {
|
|
776
864
|
return `Hello, ${args.name}!`
|
|
777
865
|
}
|
|
@@ -795,13 +883,13 @@ The `run()` function automatically:
|
|
|
795
883
|
|
|
796
884
|
#### Tunnel vs. Deployed Endpoint
|
|
797
885
|
|
|
798
|
-
| Aspect | Tunnel (Local Development) | Deployed Endpoint (Production)
|
|
799
|
-
| ----------------- | -------------------------- |
|
|
800
|
-
| Setup | Just run your code | Deploy to cloud/server
|
|
801
|
-
| URL Configuration | Not needed | Set Agent Endpoint in platform
|
|
802
|
-
| Connection | WebSocket via proxy | Direct HTTP
|
|
803
|
-
| Tunnel | Enabled (default) | Disabled (`DISABLE_TUNNEL=true`)
|
|
804
|
-
| Use case | Development & testing | Production
|
|
886
|
+
| Aspect | Tunnel (Local Development) | Deployed Endpoint (Production) |
|
|
887
|
+
| ----------------- | -------------------------- | -------------------------------- |
|
|
888
|
+
| Setup | Just run your code | Deploy to cloud/server |
|
|
889
|
+
| URL Configuration | Not needed | Set Agent Endpoint in platform |
|
|
890
|
+
| Connection | WebSocket via proxy | Direct HTTP |
|
|
891
|
+
| Tunnel | Enabled (default) | Disabled (`DISABLE_TUNNEL=true`) |
|
|
892
|
+
| Use case | Development & testing | Production |
|
|
805
893
|
|
|
806
894
|
When deploying to a hosting provider like Cloud Run, set `DISABLE_TUNNEL=true` as an environment variable. This makes `run()` start only the HTTP server without opening a WebSocket tunnel to the proxy — the platform reaches your agent directly at its public URL.
|
|
807
895
|
|
package/dist/agent.d.ts
CHANGED
|
@@ -2,9 +2,47 @@ import { type AxiosInstance } from 'axios';
|
|
|
2
2
|
import type { GetFilesParams, GetSecretsParams, GetSecretValueParams, UploadFileParams, DeleteFileParams, MarkTaskAsErroredParams, CompleteTaskParams, SendChatMessageParams, GetTaskDetailParams, GetAgentsParams, GetTasksParams, CreateTaskParams, AddLogToTaskParams, RequestHumanAssistanceParams, UpdateTaskStatusParams, ProcessParams, IntegrationCallRequest, GetChatMessagesParams, AgentChatMessagesResponse, GetFilesResponse, GetSecretsResponse, UploadFileResponse, DeleteFileResponse, GetTaskDetailResponse, GetAgentsResponse, GetTasksResponse, CreateTaskResponse, ActionSchema, DoTaskActionSchema, RespondChatMessageActionSchema } from './types';
|
|
3
3
|
import type { ChatCompletionMessageParam, ChatCompletion } from 'openai/resources/chat/completions';
|
|
4
4
|
import OpenAI from 'openai';
|
|
5
|
-
import
|
|
5
|
+
import { z } from 'zod';
|
|
6
6
|
import { Capability } from './capability';
|
|
7
7
|
import { type MCPServerConfig, MCPClient } from './mcp';
|
|
8
|
+
/** Accept inputSchema (preferred) or schema (deprecated), never both */
|
|
9
|
+
type WithInputSchema<S extends z.ZodTypeAny> = {
|
|
10
|
+
inputSchema: S;
|
|
11
|
+
schema?: never;
|
|
12
|
+
} | {
|
|
13
|
+
schema: S;
|
|
14
|
+
inputSchema?: never;
|
|
15
|
+
};
|
|
16
|
+
/** Optional inputSchema for run-less caps -- can omit entirely (uses default) */
|
|
17
|
+
type WithOptionalInputSchema<S extends z.ZodTypeAny> = {
|
|
18
|
+
inputSchema: S;
|
|
19
|
+
schema?: never;
|
|
20
|
+
} | {
|
|
21
|
+
schema: S;
|
|
22
|
+
inputSchema?: never;
|
|
23
|
+
} | {
|
|
24
|
+
inputSchema?: never;
|
|
25
|
+
schema?: never;
|
|
26
|
+
};
|
|
27
|
+
/** Capability with a run function -- inputSchema required, outputSchema not allowed */
|
|
28
|
+
type RunnableCapabilityConfig<M extends string, S extends z.ZodTypeAny> = {
|
|
29
|
+
name: string;
|
|
30
|
+
description: string;
|
|
31
|
+
run(this: Agent<M>, params: {
|
|
32
|
+
args: z.infer<S>;
|
|
33
|
+
action: ActionSchema;
|
|
34
|
+
}, messages: ChatCompletionMessageParam[]): string | Promise<string>;
|
|
35
|
+
outputSchema?: never;
|
|
36
|
+
} & WithInputSchema<S>;
|
|
37
|
+
/** Capability without run -- inputSchema optional, outputSchema optional */
|
|
38
|
+
type RunlessCapabilityConfig<S extends z.ZodTypeAny = z.ZodTypeAny> = {
|
|
39
|
+
name: string;
|
|
40
|
+
description: string;
|
|
41
|
+
run?: never;
|
|
42
|
+
outputSchema?: z.ZodTypeAny;
|
|
43
|
+
} & WithOptionalInputSchema<S>;
|
|
44
|
+
/** Union of all valid capability forms */
|
|
45
|
+
export type CapabilityConfig<M extends string, S extends z.ZodTypeAny> = RunnableCapabilityConfig<M, S> | RunlessCapabilityConfig<S>;
|
|
8
46
|
/**
|
|
9
47
|
* Configuration options for creating a new Agent instance.
|
|
10
48
|
*/
|
|
@@ -31,9 +69,9 @@ export interface AgentOptions<T extends string> {
|
|
|
31
69
|
*/
|
|
32
70
|
systemPrompt: string;
|
|
33
71
|
/**
|
|
34
|
-
*
|
|
72
|
+
* Optional OpenAI API key for direct LLM access via process().
|
|
73
|
+
* NOT required for platform-deployed agents -- use generate() or run-less capabilities instead.
|
|
35
74
|
* Can also be provided via OPENAI_API_KEY environment variable.
|
|
36
|
-
* Required when using the process() method.
|
|
37
75
|
*/
|
|
38
76
|
openaiApiKey?: string;
|
|
39
77
|
/**
|
|
@@ -82,7 +120,8 @@ export declare class Agent<M extends string = string> {
|
|
|
82
120
|
protected systemPrompt: string;
|
|
83
121
|
/**
|
|
84
122
|
* Array of capabilities (tools) available to the agent.
|
|
85
|
-
* Each capability is an instance of the Capability class with a name, description,
|
|
123
|
+
* Each capability is an instance of the Capability class with a name, description, inputSchema,
|
|
124
|
+
* and optionally a run function and/or outputSchema.
|
|
86
125
|
* @protected
|
|
87
126
|
*/
|
|
88
127
|
protected tools: Array<Capability<M, z.ZodTypeAny>>;
|
|
@@ -167,53 +206,32 @@ export declare class Agent<M extends string = string> {
|
|
|
167
206
|
private initializeMCPClients;
|
|
168
207
|
/**
|
|
169
208
|
* Adds a single capability (tool) to the agent.
|
|
170
|
-
* Each capability must have a unique name
|
|
209
|
+
* Each capability must have a unique name. Capabilities can be:
|
|
210
|
+
* - **Runnable**: has a `run` function and requires `inputSchema` (or deprecated `schema`)
|
|
211
|
+
* - **Run-less**: no `run` function -- the runtime handles execution via LLM.
|
|
212
|
+
* `inputSchema` is optional (defaults to `{ input: z.string() }`), `outputSchema` is optional.
|
|
171
213
|
*
|
|
172
214
|
* @template S - The Zod schema type for the capability's parameters
|
|
173
|
-
* @param
|
|
174
|
-
* @
|
|
175
|
-
* @param {string} capability.description - Description of what the capability does
|
|
176
|
-
* @param {S} capability.schema - Zod schema defining the capability's parameters
|
|
177
|
-
* @param {Function} capability.run - Function that implements the capability's behavior
|
|
178
|
-
* @param {Object} capability.run.params - Parameters for the run function
|
|
179
|
-
* @param {z.infer<S>} capability.run.params.args - Validated arguments matching the schema
|
|
180
|
-
* @param {ActionSchema} [capability.run.params.action] - Optional action context
|
|
181
|
-
* @param {ChatCompletionMessageParam[]} capability.run.messages - Chat message history
|
|
182
|
-
* @returns {this} The agent instance for method chaining
|
|
215
|
+
* @param capability - The capability configuration
|
|
216
|
+
* @returns The agent instance for method chaining
|
|
183
217
|
* @throws {Error} If a capability with the same name already exists
|
|
218
|
+
* @throws {Error} If both `inputSchema` and `schema` are provided
|
|
219
|
+
* @throws {Error} If both `run` and `outputSchema` are provided
|
|
220
|
+
* @throws {Error} If a runnable capability omits `inputSchema`/`schema`
|
|
184
221
|
*/
|
|
185
|
-
addCapability<S extends z.ZodTypeAny>(
|
|
186
|
-
name: string;
|
|
187
|
-
description: string;
|
|
188
|
-
schema: S;
|
|
189
|
-
run(this: Agent<M>, params: {
|
|
190
|
-
args: z.infer<S>;
|
|
191
|
-
action?: ActionSchema;
|
|
192
|
-
}, messages: ChatCompletionMessageParam[]): string | Promise<string>;
|
|
193
|
-
}): this;
|
|
222
|
+
addCapability<S extends z.ZodTypeAny>(capability: CapabilityConfig<M, S>): this;
|
|
194
223
|
/**
|
|
195
224
|
* Adds multiple capabilities (tools) to the agent at once.
|
|
196
225
|
* Each capability must have a unique name and not conflict with existing capabilities.
|
|
226
|
+
* Each element can be runnable or run-less independently.
|
|
197
227
|
*
|
|
198
228
|
* @template T - Tuple of Zod schema types for the capabilities' parameters
|
|
199
|
-
* @param
|
|
200
|
-
* @
|
|
201
|
-
* @param {string} capabilities[].description - Description of what each capability does
|
|
202
|
-
* @param {T[number]} capabilities[].schema - Zod schema defining each capability's parameters
|
|
203
|
-
* @param {Function} capabilities[].run - Function that implements each capability's behavior
|
|
204
|
-
* @returns {this} The agent instance for method chaining
|
|
229
|
+
* @param capabilities - Array of capability configurations
|
|
230
|
+
* @returns The agent instance for method chaining
|
|
205
231
|
* @throws {Error} If any capability has a name that already exists
|
|
206
232
|
*/
|
|
207
233
|
addCapabilities<T extends readonly [z.ZodTypeAny, ...z.ZodTypeAny[]]>(capabilities: {
|
|
208
|
-
[K in keyof T]:
|
|
209
|
-
name: string;
|
|
210
|
-
description: string;
|
|
211
|
-
schema: T[K];
|
|
212
|
-
run(this: Agent<M>, params: {
|
|
213
|
-
args: z.infer<T[K]>;
|
|
214
|
-
action?: ActionSchema;
|
|
215
|
-
}, messages: ChatCompletionMessageParam[]): string | Promise<string>;
|
|
216
|
-
};
|
|
234
|
+
[K in keyof T]: CapabilityConfig<M, T[K]>;
|
|
217
235
|
}): this;
|
|
218
236
|
/**
|
|
219
237
|
* Gets files in a workspace.
|
|
@@ -370,6 +388,37 @@ export declare class Agent<M extends string = string> {
|
|
|
370
388
|
* @returns {Promise<UpdateTaskStatusResponse>} The updated task details
|
|
371
389
|
*/
|
|
372
390
|
updateTaskStatus(params: UpdateTaskStatusParams): Promise<undefined>;
|
|
391
|
+
/**
|
|
392
|
+
* Generate text via the OpenServ runtime.
|
|
393
|
+
* Billed to the workspace/task in the action.
|
|
394
|
+
* Use this inside custom `run` functions when you need LLM generation without your own OpenAI key.
|
|
395
|
+
*
|
|
396
|
+
* @param params.prompt - The prompt for the LLM
|
|
397
|
+
* @param params.messages - Optional conversation history for context
|
|
398
|
+
* @param params.action - Action context (required for billing)
|
|
399
|
+
* @returns The generated text
|
|
400
|
+
*/
|
|
401
|
+
generate(params: {
|
|
402
|
+
prompt: string;
|
|
403
|
+
messages?: ChatCompletionMessageParam[];
|
|
404
|
+
action: ActionSchema;
|
|
405
|
+
}): Promise<string>;
|
|
406
|
+
/**
|
|
407
|
+
* Generate a structured object via the OpenServ runtime.
|
|
408
|
+
* Billed to the workspace/task in the action.
|
|
409
|
+
*
|
|
410
|
+
* @param params.prompt - The prompt for the LLM
|
|
411
|
+
* @param params.messages - Optional conversation history for context
|
|
412
|
+
* @param params.outputSchema - Zod schema for structured output
|
|
413
|
+
* @param params.action - Action context (required for billing)
|
|
414
|
+
* @returns The generated object, validated against the schema
|
|
415
|
+
*/
|
|
416
|
+
generate<T extends z.ZodTypeAny>(params: {
|
|
417
|
+
prompt: string;
|
|
418
|
+
messages?: ChatCompletionMessageParam[];
|
|
419
|
+
outputSchema: T;
|
|
420
|
+
action: ActionSchema;
|
|
421
|
+
}): Promise<z.infer<T>>;
|
|
373
422
|
/**
|
|
374
423
|
* Processes a conversation with OpenAI, handling tool calls iteratively until completion.
|
|
375
424
|
*
|
|
@@ -394,15 +443,18 @@ export declare class Agent<M extends string = string> {
|
|
|
394
443
|
/**
|
|
395
444
|
* Handles execution of a specific tool/capability.
|
|
396
445
|
*
|
|
446
|
+
* The runtime calls this for both task execution (do-task) and chat (respond-chat-message),
|
|
447
|
+
* always providing the action context in the request body.
|
|
448
|
+
*
|
|
397
449
|
* @param {Object} req - The request object
|
|
398
450
|
* @param {Object} req.params - Request parameters
|
|
399
451
|
* @param {string} req.params.toolName - Name of the tool to execute
|
|
400
452
|
* @param {Object} req.body - Request body
|
|
401
453
|
* @param {z.infer<z.ZodTypeAny>} [req.body.args] - Arguments for the tool
|
|
402
|
-
* @param {ActionSchema}
|
|
454
|
+
* @param {ActionSchema} req.body.action - Action context (required)
|
|
403
455
|
* @param {ChatCompletionMessageParam[]} [req.body.messages] - Message history
|
|
404
456
|
* @returns {Promise<{result: string}>} The result of the tool execution
|
|
405
|
-
* @throws {BadRequest} If tool name is missing
|
|
457
|
+
* @throws {BadRequest} If tool name is missing, tool is not found, or action is missing
|
|
406
458
|
* @throws {Error} If tool execution fails
|
|
407
459
|
*/
|
|
408
460
|
handleToolRoute(req: {
|
|
@@ -479,4 +531,5 @@ export declare class Agent<M extends string = string> {
|
|
|
479
531
|
*/
|
|
480
532
|
private addMCPToolsAsCapabilities;
|
|
481
533
|
}
|
|
534
|
+
export {};
|
|
482
535
|
//# sourceMappingURL=agent.d.ts.map
|
package/dist/agent.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,aAAa,EAAE,MAAM,OAAO,CAAA;AAUjD,OAAO,KAAK,EACV,cAAc,EACd,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,uBAAuB,EACvB,kBAAkB,EAClB,qBAAqB,EACrB,mBAAmB,EACnB,eAAe,EACf,cAAc,EACd,gBAAgB,EAChB,kBAAkB,EAClB,4BAA4B,EAC5B,sBAAsB,EACtB,aAAa,EACb,sBAAsB,EACtB,qBAAqB,EACrB,yBAAyB,EACzB,gBAAgB,EAEhB,kBAAkB,EAClB,kBAAkB,EAClB,kBAAkB,EAClB,qBAAqB,EACrB,iBAAiB,EACjB,gBAAgB,EAChB,kBAAkB,EAOlB,YAAY,EACZ,kBAAkB,EAClB,8BAA8B,EAC/B,MAAM,SAAS,CAAA;AAEhB,OAAO,KAAK,EACV,0BAA0B,EAE1B,cAAc,EACf,MAAM,mCAAmC,CAAA;AAI1C,OAAO,MAAM,MAAM,QAAQ,CAAA;AAC3B,OAAO,
|
|
1
|
+
{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}
|