@signalwire/sdk 2.0.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/.github/workflows/publish.yml +27 -0
- package/.github/workflows/test.yml +17 -0
- package/CLAUDE.md +112 -0
- package/README.md +254 -0
- package/docs/MIGRATION-2.0.md +81 -0
- package/docs/agent-guide.md +869 -0
- package/docs/agent_guide.md +1026 -0
- package/docs/api-reference.md +2420 -0
- package/docs/api_reference.md +1301 -0
- package/docs/architecture.md +843 -0
- package/docs/cli-guide.md +579 -0
- package/docs/cli_guide.md +448 -0
- package/docs/cloud_functions_guide.md +474 -0
- package/docs/configuration.md +422 -0
- package/docs/contexts-guide.md +787 -0
- package/docs/contexts_guide.md +511 -0
- package/docs/datamap-guide.md +1141 -0
- package/docs/datamap_guide.md +595 -0
- package/docs/llm_parameters.md +239 -0
- package/docs/mcp_gateway_reference.md +648 -0
- package/docs/mcp_integration.md +108 -0
- package/docs/prefabs-guide.md +800 -0
- package/docs/sdk_features.md +477 -0
- package/docs/security.md +436 -0
- package/docs/serverless-guide.md +513 -0
- package/docs/skills-guide.md +857 -0
- package/docs/skills-system.md +301 -0
- package/docs/skills_parameter_schema.md +392 -0
- package/docs/skills_system.md +467 -0
- package/docs/swaig-reference.md +1627 -0
- package/docs/swaig_reference.md +910 -0
- package/docs/swml_service_guide.md +600 -0
- package/docs/third_party_skills.md +533 -0
- package/docs/web_service.md +677 -0
- package/examples/README.md +131 -0
- package/examples/advanced-datamap.ts +100 -0
- package/examples/advanced-dynamic-config.ts +70 -0
- package/examples/auto-vivified.ts +94 -0
- package/examples/call-flow.ts +63 -0
- package/examples/comprehensive-dynamic.ts +125 -0
- package/examples/contexts-steps.ts +65 -0
- package/examples/custom-path.ts +45 -0
- package/examples/datamap-tools.ts +55 -0
- package/examples/datasphere-multi-instance.ts +63 -0
- package/examples/datasphere-serverless-env.ts +68 -0
- package/examples/datasphere-webhook-env.ts +66 -0
- package/examples/datasphere.ts +37 -0
- package/examples/declarative.ts +100 -0
- package/examples/dynamic-config.ts +54 -0
- package/examples/dynamic-info-gatherer.ts +69 -0
- package/examples/dynamic-swml-service.ts +67 -0
- package/examples/gather-info.ts +71 -0
- package/examples/gather-per-question-functions-demo.ts +140 -0
- package/examples/joke-agent.ts +34 -0
- package/examples/kubernetes-agent.ts +45 -0
- package/examples/llm-params.ts +69 -0
- package/examples/mcp-agent.ts +84 -0
- package/examples/mcp-gateway.ts +35 -0
- package/examples/multi-agent.ts +73 -0
- package/examples/multi-endpoint.ts +79 -0
- package/examples/pom-prompt.ts +71 -0
- package/examples/prefab-concierge.ts +47 -0
- package/examples/prefab-faq.ts +54 -0
- package/examples/prefab-info-gatherer.ts +33 -0
- package/examples/prefab-receptionist.ts +36 -0
- package/examples/prefab-survey.ts +68 -0
- package/examples/record-call.ts +67 -0
- package/examples/relay-demo.ts +33 -0
- package/examples/room-and-sip.ts +94 -0
- package/examples/serverless-lambda.ts +35 -0
- package/examples/session-state.ts +83 -0
- package/examples/simple-agent.ts +36 -0
- package/examples/simple-static.ts +29 -0
- package/examples/skills-demo.ts +38 -0
- package/examples/step-function-inheritance-demo.ts +124 -0
- package/examples/swaig-features.ts +187 -0
- package/examples/swml-service-routing.ts +66 -0
- package/examples/swml-service.ts +38 -0
- package/examples/tap.ts +68 -0
- package/examples/verb-methods.ts +45 -0
- package/examples/web-search-multi-instance.ts +72 -0
- package/examples/web-search.ts +38 -0
- package/examples/wikipedia.ts +36 -0
- package/livewire/README.md +140 -0
- package/livewire/docs/migration-guide.md +228 -0
- package/livewire/examples/livewire-basic-agent.ts +74 -0
- package/livewire/examples/livewire-handoff.ts +197 -0
- package/livewire/examples/livewire-multi-tool.ts +117 -0
- package/package.json +38 -0
- package/relay/README.md +70 -0
- package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
- package/relay/docs/call-methods.md +474 -0
- package/relay/docs/client-reference.md +142 -0
- package/relay/docs/events.md +134 -0
- package/relay/docs/getting-started.md +134 -0
- package/relay/docs/guide.md +306 -0
- package/relay/docs/messaging.md +182 -0
- package/relay/examples/relay-inbound.ts +66 -0
- package/relay/examples/relay-messaging.ts +71 -0
- package/relay/examples/relay-outbound.ts +76 -0
- package/rest/README.md +95 -0
- package/rest/docs/calling.md +273 -0
- package/rest/docs/client-reference.md +107 -0
- package/rest/docs/compat.md +204 -0
- package/rest/docs/fabric.md +183 -0
- package/rest/docs/getting-started.md +110 -0
- package/rest/docs/guide.md +351 -0
- package/rest/docs/namespaces.md +285 -0
- package/rest/examples/rest-10dlc-registration.ts +161 -0
- package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
- package/rest/examples/rest-calling-play-and-record.ts +91 -0
- package/rest/examples/rest-client.ts +65 -0
- package/rest/examples/rest-compat-laml.ts +210 -0
- package/rest/examples/rest-datasphere-search.ts +82 -0
- package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
- package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
- package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
- package/rest/examples/rest-manage-resources.ts +65 -0
- package/rest/examples/rest-phone-number-management.ts +197 -0
- package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
- package/rest/examples/rest-video-rooms.ts +186 -0
- package/src/AgentBase.ts +2489 -0
- package/src/AgentServer.ts +415 -0
- package/src/AuthHandler.ts +256 -0
- package/src/ConfigLoader.ts +447 -0
- package/src/ContextBuilder.ts +1150 -0
- package/src/DataMap.ts +449 -0
- package/src/FunctionResult.ts +866 -0
- package/src/Logger.ts +337 -0
- package/src/PomBuilder.ts +439 -0
- package/src/PromptManager.ts +133 -0
- package/src/SWMLHandler.ts +298 -0
- package/src/SWMLService.ts +717 -0
- package/src/SchemaUtils.ts +361 -0
- package/src/SecurityUtils.ts +153 -0
- package/src/ServerlessAdapter.ts +221 -0
- package/src/SessionManager.ts +311 -0
- package/src/SslConfig.ts +118 -0
- package/src/SwaigFunction.ts +276 -0
- package/src/SwmlBuilder.ts +258 -0
- package/src/SwmlVerbMethods.generated.ts +234 -0
- package/src/TypeInference.ts +181 -0
- package/src/WebService.ts +619 -0
- package/src/cli/agent-loader.ts +166 -0
- package/src/cli/mock-data.ts +111 -0
- package/src/cli/swaig-test.ts +452 -0
- package/src/generateVerbTypes.ts +322 -0
- package/src/index.ts +167 -0
- package/src/livewire/index.ts +950 -0
- package/src/prefabs/ConciergeAgent.ts +287 -0
- package/src/prefabs/FAQBotAgent.ts +384 -0
- package/src/prefabs/InfoGathererAgent.ts +339 -0
- package/src/prefabs/ReceptionistAgent.ts +366 -0
- package/src/prefabs/SurveyAgent.ts +646 -0
- package/src/prefabs/index.ts +27 -0
- package/src/relay/Action.ts +314 -0
- package/src/relay/Call.ts +854 -0
- package/src/relay/Deferred.ts +71 -0
- package/src/relay/Message.ts +148 -0
- package/src/relay/RelayClient.ts +1036 -0
- package/src/relay/RelayError.ts +14 -0
- package/src/relay/RelayEvent.ts +892 -0
- package/src/relay/constants.ts +132 -0
- package/src/relay/index.ts +123 -0
- package/src/relay/types.ts +149 -0
- package/src/rest/HttpClient.ts +103 -0
- package/src/rest/RestError.ts +31 -0
- package/src/rest/base/BaseResource.ts +19 -0
- package/src/rest/base/CrudResource.ts +51 -0
- package/src/rest/base/CrudWithAddresses.ts +26 -0
- package/src/rest/index.ts +200 -0
- package/src/rest/namespaces/addresses.ts +32 -0
- package/src/rest/namespaces/calling.ts +187 -0
- package/src/rest/namespaces/chat.ts +20 -0
- package/src/rest/namespaces/compat.ts +352 -0
- package/src/rest/namespaces/datasphere.ts +45 -0
- package/src/rest/namespaces/fabric.ts +222 -0
- package/src/rest/namespaces/imported-numbers.ts +20 -0
- package/src/rest/namespaces/logs.ts +84 -0
- package/src/rest/namespaces/lookup.ts +21 -0
- package/src/rest/namespaces/mfa.ts +30 -0
- package/src/rest/namespaces/number-groups.ts +38 -0
- package/src/rest/namespaces/phone-numbers.ts +44 -0
- package/src/rest/namespaces/project.ts +36 -0
- package/src/rest/namespaces/pubsub.ts +20 -0
- package/src/rest/namespaces/queues.ts +33 -0
- package/src/rest/namespaces/recordings.ts +28 -0
- package/src/rest/namespaces/registry.ts +101 -0
- package/src/rest/namespaces/short-codes.ts +28 -0
- package/src/rest/namespaces/sip-profile.ts +25 -0
- package/src/rest/namespaces/verified-callers.ts +27 -0
- package/src/rest/namespaces/video.ts +165 -0
- package/src/rest/pagination.ts +84 -0
- package/src/rest/types.ts +61 -0
- package/src/schema.json +12250 -0
- package/src/skills/SkillBase.ts +547 -0
- package/src/skills/SkillManager.ts +415 -0
- package/src/skills/SkillRegistry.ts +367 -0
- package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
- package/src/skills/builtin/ask_claude.ts +241 -0
- package/src/skills/builtin/claude_skills.ts +978 -0
- package/src/skills/builtin/custom_skills.ts +312 -0
- package/src/skills/builtin/datasphere.ts +438 -0
- package/src/skills/builtin/datasphere_serverless.ts +339 -0
- package/src/skills/builtin/datetime.ts +130 -0
- package/src/skills/builtin/google_maps.ts +651 -0
- package/src/skills/builtin/index.ts +88 -0
- package/src/skills/builtin/info_gatherer.ts +405 -0
- package/src/skills/builtin/joke.ts +191 -0
- package/src/skills/builtin/math.ts +142 -0
- package/src/skills/builtin/mcp_gateway.ts +677 -0
- package/src/skills/builtin/native_vector_search.ts +901 -0
- package/src/skills/builtin/play_background_file.ts +358 -0
- package/src/skills/builtin/spider.ts +869 -0
- package/src/skills/builtin/swml_transfer.ts +635 -0
- package/src/skills/builtin/weather_api.ts +248 -0
- package/src/skills/builtin/web_search.ts +1074 -0
- package/src/skills/builtin/wikipedia_search.ts +299 -0
- package/src/skills/index.ts +12 -0
- package/src/types.ts +132 -0
- package/tests/AgentBase.test.ts +1093 -0
- package/tests/AgentServer.test.ts +126 -0
- package/tests/AuthHandler.test.ts +133 -0
- package/tests/ConfigLoader.test.ts +151 -0
- package/tests/ContextBuilder.test.ts +108 -0
- package/tests/DataMap.test.ts +367 -0
- package/tests/EphemeralSkillCopy.test.ts +107 -0
- package/tests/FunctionResult.test.ts +298 -0
- package/tests/GracefulShutdown.test.ts +46 -0
- package/tests/Logger.test.ts +420 -0
- package/tests/PomBuilder.test.ts +228 -0
- package/tests/ProxyDetection.test.ts +228 -0
- package/tests/SWMLService.test.ts +320 -0
- package/tests/SWMLVerbHandler.test.ts +523 -0
- package/tests/SchemaUtils.test.ts +106 -0
- package/tests/SchemaUtils.verb.test.ts +206 -0
- package/tests/SecurityUtils.test.ts +192 -0
- package/tests/ServerlessAdapter.test.ts +222 -0
- package/tests/SessionManager.test.ts +257 -0
- package/tests/SkillBaseFeatures.test.ts +130 -0
- package/tests/SkillMultiInstance.test.ts +102 -0
- package/tests/SkillParameterSchemas.test.ts +134 -0
- package/tests/SkillRegistrySchema.test.ts +84 -0
- package/tests/SslConfig.test.ts +97 -0
- package/tests/SwmlBuilder.test.ts +400 -0
- package/tests/TypeInference.test.ts +165 -0
- package/tests/VerbHandlerRegistry.test.ts +128 -0
- package/tests/cli/mock-data.test.ts +113 -0
- package/tests/cli/swaig-test.test.ts +108 -0
- package/tests/examples.test.ts +194 -0
- package/tests/fixtures/scrape-parity/README.md +53 -0
- package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
- package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
- package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
- package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
- package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
- package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
- package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
- package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
- package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
- package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
- package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
- package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
- package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
- package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
- package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
- package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
- package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
- package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
- package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
- package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
- package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
- package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
- package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
- package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
- package/tests/fixtures/scrape-parity/python_extract.py +109 -0
- package/tests/livewire/livewire.test.ts +780 -0
- package/tests/mcp.test.ts +221 -0
- package/tests/prefabs/prefabs.test.ts +1093 -0
- package/tests/relay/Action.test.ts +392 -0
- package/tests/relay/Call.test.ts +535 -0
- package/tests/relay/Deferred.test.ts +71 -0
- package/tests/relay/Message.test.ts +164 -0
- package/tests/relay/RelayClient.test.ts +779 -0
- package/tests/relay/RelayEvent.test.ts +463 -0
- package/tests/relay/helpers.ts +79 -0
- package/tests/rest/HttpClient.test.ts +274 -0
- package/tests/rest/RestError.test.ts +53 -0
- package/tests/rest/calling.test.ts +156 -0
- package/tests/rest/client.test.ts +197 -0
- package/tests/rest/compat.test.ts +335 -0
- package/tests/rest/datasphere.test.ts +71 -0
- package/tests/rest/fabric.test.ts +186 -0
- package/tests/rest/helpers.ts +95 -0
- package/tests/rest/logs.test.ts +68 -0
- package/tests/rest/pagination.test.ts +133 -0
- package/tests/rest/registry.test.ts +94 -0
- package/tests/rest/relay-rest.test.ts +290 -0
- package/tests/rest/video.test.ts +173 -0
- package/tests/setup.ts +6 -0
- package/tests/skills/SkillBase.test.ts +108 -0
- package/tests/skills/SkillManager.test.ts +268 -0
- package/tests/skills/SkillRegistry.test.ts +176 -0
- package/tests/skills/builtin.test.ts +1472 -0
- package/tests/skills/claude-skills.test.ts +54 -0
- package/tests/skills/custom-skills.test.ts +53 -0
- package/tests/skills/datasphere-serverless.test.ts +70 -0
- package/tests/skills/datasphere.test.ts +107 -0
- package/tests/skills/datetime.test.ts +101 -0
- package/tests/skills/google-maps.test.ts +78 -0
- package/tests/skills/info-gatherer.test.ts +411 -0
- package/tests/skills/joke.test.ts +81 -0
- package/tests/skills/math.test.ts +68 -0
- package/tests/skills/mcp-gateway.test.ts +101 -0
- package/tests/skills/play-background.test.ts +54 -0
- package/tests/skills/spider.test.ts +108 -0
- package/tests/skills/swml-transfer.test.ts +178 -0
- package/tests/skills/trivia.test.ts +54 -0
- package/tests/skills/vector-search.test.ts +135 -0
- package/tests/skills/weather-api.test.ts +77 -0
- package/tests/skills/web-search-parity.test.ts +59 -0
- package/tests/skills/web-search.test.ts +103 -0
- package/tests/skills/wikipedia.test.ts +63 -0
- package/tsconfig.json +18 -0
- package/vitest.config.ts +9 -0
|
@@ -0,0 +1,339 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* InfoGathererAgent - Prefab agent for collecting answers to a series of
|
|
3
|
+
* questions.
|
|
4
|
+
*
|
|
5
|
+
* Ported from the Python SDK `signalwire.prefabs.info_gatherer.InfoGathererAgent`.
|
|
6
|
+
* Supports both static (questions provided at init) and dynamic (questions
|
|
7
|
+
* determined by a callback function per request) configuration modes.
|
|
8
|
+
*/
|
|
9
|
+
|
|
10
|
+
import { AgentBase } from '../AgentBase.js';
|
|
11
|
+
import { FunctionResult } from '../FunctionResult.js';
|
|
12
|
+
import type { AgentOptions } from '../types.js';
|
|
13
|
+
|
|
14
|
+
// ── Config types ────────────────────────────────────────────────────────────
|
|
15
|
+
|
|
16
|
+
/** A single question in the information-gathering flow. */
|
|
17
|
+
export interface InfoGathererQuestion {
|
|
18
|
+
/** Identifier used as the key when storing the caller's answer. */
|
|
19
|
+
key_name: string;
|
|
20
|
+
/** The question text to ask the caller. */
|
|
21
|
+
question_text: string;
|
|
22
|
+
/** When true, the agent insists the caller confirms before submitting. */
|
|
23
|
+
confirm?: boolean;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* Callback invoked on each incoming SWML request to produce the list of
|
|
28
|
+
* questions for that request. Mirrors Python's `set_question_callback`.
|
|
29
|
+
* @returns a list of questions (may be async).
|
|
30
|
+
*/
|
|
31
|
+
export type InfoGathererQuestionCallback = (
|
|
32
|
+
queryParams: Record<string, string>,
|
|
33
|
+
bodyParams: Record<string, unknown>,
|
|
34
|
+
headers: Record<string, string>,
|
|
35
|
+
) => InfoGathererQuestion[] | Promise<InfoGathererQuestion[]>;
|
|
36
|
+
|
|
37
|
+
/** Configuration for the InfoGathererAgent. */
|
|
38
|
+
export interface InfoGathererConfig {
|
|
39
|
+
/**
|
|
40
|
+
* Optional list of questions to ask. When omitted, the agent runs in
|
|
41
|
+
* dynamic mode and resolves questions via the callback registered with
|
|
42
|
+
* `setQuestionCallback()` (or via `questionCallback` below).
|
|
43
|
+
*/
|
|
44
|
+
questions?: InfoGathererQuestion[];
|
|
45
|
+
/**
|
|
46
|
+
* Convenience alternative to calling `setQuestionCallback()` after
|
|
47
|
+
* construction. Only consulted when `questions` is not provided.
|
|
48
|
+
*/
|
|
49
|
+
questionCallback?: InfoGathererQuestionCallback;
|
|
50
|
+
/** Agent display name (defaults to `"info_gatherer"`). */
|
|
51
|
+
name?: string;
|
|
52
|
+
/** HTTP route for this agent (defaults to `"/info_gatherer"`). */
|
|
53
|
+
route?: string;
|
|
54
|
+
/** Additional AgentBase options forwarded to super(). */
|
|
55
|
+
agentOptions?: Partial<AgentOptions>;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
// ── Agent ───────────────────────────────────────────────────────────────────
|
|
59
|
+
|
|
60
|
+
/** Fallback questions used in dynamic mode when no callback is registered or the callback throws. */
|
|
61
|
+
const FALLBACK_QUESTIONS: InfoGathererQuestion[] = [
|
|
62
|
+
{ key_name: 'name', question_text: 'What is your name?' },
|
|
63
|
+
{ key_name: 'message', question_text: 'How can I help you today?' },
|
|
64
|
+
];
|
|
65
|
+
|
|
66
|
+
/** Prefab agent that gathers caller information one question at a time. */
|
|
67
|
+
export class InfoGathererAgent extends AgentBase {
|
|
68
|
+
private staticQuestions: InfoGathererQuestion[] | null;
|
|
69
|
+
private questionCallback: InfoGathererQuestionCallback | null = null;
|
|
70
|
+
|
|
71
|
+
/**
|
|
72
|
+
* Create an InfoGathererAgent.
|
|
73
|
+
* @param config - Either `questions` (static mode) or leave omitted and use
|
|
74
|
+
* `questionCallback` / `setQuestionCallback()` (dynamic mode).
|
|
75
|
+
*/
|
|
76
|
+
constructor(config: InfoGathererConfig = {}) {
|
|
77
|
+
const agentName = config.name ?? 'info_gatherer';
|
|
78
|
+
super({
|
|
79
|
+
name: agentName,
|
|
80
|
+
route: config.route ?? '/info_gatherer',
|
|
81
|
+
usePom: true,
|
|
82
|
+
...config.agentOptions,
|
|
83
|
+
});
|
|
84
|
+
|
|
85
|
+
if (config.questions !== undefined) {
|
|
86
|
+
InfoGathererAgent.validateQuestions(config.questions);
|
|
87
|
+
this.staticQuestions = config.questions;
|
|
88
|
+
this.setGlobalData({
|
|
89
|
+
questions: config.questions,
|
|
90
|
+
question_index: 0,
|
|
91
|
+
answers: [],
|
|
92
|
+
});
|
|
93
|
+
this.buildPrompt('static');
|
|
94
|
+
} else {
|
|
95
|
+
this.staticQuestions = null;
|
|
96
|
+
this.buildPrompt('dynamic');
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
if (config.questionCallback) {
|
|
100
|
+
this.questionCallback = config.questionCallback;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
// AI behavior parameters (mirrors Python _configure_agent_settings)
|
|
104
|
+
this.setParams({
|
|
105
|
+
end_of_speech_timeout: 800,
|
|
106
|
+
speech_event_timeout: 1000,
|
|
107
|
+
});
|
|
108
|
+
|
|
109
|
+
// Register tools after all fields are initialized
|
|
110
|
+
this.defineTools();
|
|
111
|
+
}
|
|
112
|
+
|
|
113
|
+
/**
|
|
114
|
+
* Register a callback for dynamic question configuration. The callback is
|
|
115
|
+
* invoked on each incoming SWML request with the query params, body, and
|
|
116
|
+
* headers, and must return the list of questions to ask on that call.
|
|
117
|
+
* Mirrors Python `set_question_callback`.
|
|
118
|
+
*/
|
|
119
|
+
setQuestionCallback(callback: InfoGathererQuestionCallback): this {
|
|
120
|
+
this.questionCallback = callback;
|
|
121
|
+
return this;
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
private static validateQuestions(questions: unknown): asserts questions is InfoGathererQuestion[] {
|
|
125
|
+
if (!Array.isArray(questions) || questions.length === 0) {
|
|
126
|
+
throw new Error('At least one question is required');
|
|
127
|
+
}
|
|
128
|
+
for (let i = 0; i < questions.length; i++) {
|
|
129
|
+
const q = questions[i] as Record<string, unknown>;
|
|
130
|
+
if (!q || typeof q !== 'object') {
|
|
131
|
+
throw new Error(`Question ${i + 1} must be an object`);
|
|
132
|
+
}
|
|
133
|
+
if (typeof q['key_name'] !== 'string' || !q['key_name']) {
|
|
134
|
+
throw new Error(`Question ${i + 1} is missing 'key_name' field`);
|
|
135
|
+
}
|
|
136
|
+
if (typeof q['question_text'] !== 'string' || !q['question_text']) {
|
|
137
|
+
throw new Error(`Question ${i + 1} is missing 'question_text' field`);
|
|
138
|
+
}
|
|
139
|
+
}
|
|
140
|
+
}
|
|
141
|
+
|
|
142
|
+
private buildPrompt(mode: 'static' | 'dynamic'): void {
|
|
143
|
+
const body =
|
|
144
|
+
mode === 'dynamic'
|
|
145
|
+
? 'Your role is to gather information by asking questions. Begin by asking the user if they are ready to answer some questions. If they confirm they are ready, call the start_questions function to begin the process.'
|
|
146
|
+
: 'Your role is to get answers to a series of questions. Begin by asking the user if they are ready to answer some questions. If they confirm they are ready, call the start_questions function to begin the process.';
|
|
147
|
+
this.promptAddSection('Objective', { body });
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
/**
|
|
151
|
+
* Generate the instruction text for asking a question. Mirrors Python's
|
|
152
|
+
* `_generate_question_instruction`.
|
|
153
|
+
*/
|
|
154
|
+
private generateQuestionInstruction(
|
|
155
|
+
questionText: string,
|
|
156
|
+
needsConfirmation: boolean,
|
|
157
|
+
isFirstQuestion = false,
|
|
158
|
+
): string {
|
|
159
|
+
let instruction = isFirstQuestion
|
|
160
|
+
? `Ask the user to answer the following question: ${questionText}\n\n`
|
|
161
|
+
: `Previous Answer recorded. Now ask the user to answer the following question: ${questionText}\n\n`;
|
|
162
|
+
|
|
163
|
+
instruction +=
|
|
164
|
+
'Make sure the answer fits the scope and context of the question before submitting it. ';
|
|
165
|
+
|
|
166
|
+
if (needsConfirmation) {
|
|
167
|
+
instruction +=
|
|
168
|
+
'Insist that the user confirms the answer as many times as needed until they say it is correct.';
|
|
169
|
+
} else {
|
|
170
|
+
instruction += "You don't need the user to confirm the answer to this question.";
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
return instruction;
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
// ── Lifecycle: onSwmlRequest (dynamic mode hook) ──────────────────────
|
|
177
|
+
|
|
178
|
+
/**
|
|
179
|
+
* Handle dynamic configuration using the registered callback. Returns the
|
|
180
|
+
* per-request global_data payload which AgentBase merges into the SWML
|
|
181
|
+
* response. Mirrors Python's `on_swml_request` return-dict contract.
|
|
182
|
+
*/
|
|
183
|
+
override async onSwmlRequest(
|
|
184
|
+
rawData: Record<string, unknown>,
|
|
185
|
+
): Promise<Record<string, unknown> | void> {
|
|
186
|
+
// Static mode: nothing to do.
|
|
187
|
+
if (this.staticQuestions !== null) return;
|
|
188
|
+
|
|
189
|
+
// Dynamic mode with no callback: return fallback questions as global_data.
|
|
190
|
+
if (!this.questionCallback) {
|
|
191
|
+
return {
|
|
192
|
+
global_data: {
|
|
193
|
+
questions: FALLBACK_QUESTIONS,
|
|
194
|
+
question_index: 0,
|
|
195
|
+
answers: [],
|
|
196
|
+
},
|
|
197
|
+
};
|
|
198
|
+
}
|
|
199
|
+
|
|
200
|
+
// Build callback inputs from the incoming raw data.
|
|
201
|
+
const queryParams = this.extractRecord(rawData['query_params']);
|
|
202
|
+
const headers = this.extractRecord(rawData['headers']);
|
|
203
|
+
const bodyParams = rawData;
|
|
204
|
+
|
|
205
|
+
try {
|
|
206
|
+
const questions = await this.questionCallback(queryParams, bodyParams, headers);
|
|
207
|
+
InfoGathererAgent.validateQuestions(questions);
|
|
208
|
+
return {
|
|
209
|
+
global_data: {
|
|
210
|
+
questions,
|
|
211
|
+
question_index: 0,
|
|
212
|
+
answers: [],
|
|
213
|
+
},
|
|
214
|
+
};
|
|
215
|
+
} catch (err) {
|
|
216
|
+
this.log.error(`Error in question callback: ${String(err)}`);
|
|
217
|
+
return {
|
|
218
|
+
global_data: {
|
|
219
|
+
questions: FALLBACK_QUESTIONS,
|
|
220
|
+
question_index: 0,
|
|
221
|
+
answers: [],
|
|
222
|
+
},
|
|
223
|
+
};
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
|
|
227
|
+
private extractRecord(value: unknown): Record<string, string> {
|
|
228
|
+
if (value && typeof value === 'object' && !Array.isArray(value)) {
|
|
229
|
+
const result: Record<string, string> = {};
|
|
230
|
+
for (const [k, v] of Object.entries(value as Record<string, unknown>)) {
|
|
231
|
+
if (typeof v === 'string') result[k] = v;
|
|
232
|
+
else if (v !== null && v !== undefined) result[k] = String(v);
|
|
233
|
+
}
|
|
234
|
+
return result;
|
|
235
|
+
}
|
|
236
|
+
return {};
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
// ── Tool registration ─────────────────────────────────────────────────
|
|
240
|
+
|
|
241
|
+
/** Register the `start_questions` and `submit_answer` SWAIG tools. */
|
|
242
|
+
protected override defineTools(): void {
|
|
243
|
+
// Tool: start_questions
|
|
244
|
+
this.defineTool({
|
|
245
|
+
name: 'start_questions',
|
|
246
|
+
description: 'Start the question sequence with the first question',
|
|
247
|
+
parameters: {
|
|
248
|
+
type: 'object',
|
|
249
|
+
properties: {},
|
|
250
|
+
},
|
|
251
|
+
handler: (_args: Record<string, unknown>, rawData: Record<string, unknown>) => {
|
|
252
|
+
const globalData = (rawData['global_data'] as Record<string, unknown>) ?? {};
|
|
253
|
+
const questions = (globalData['questions'] as InfoGathererQuestion[]) ?? [];
|
|
254
|
+
const questionIndex = (globalData['question_index'] as number) ?? 0;
|
|
255
|
+
|
|
256
|
+
if (!questions || questionIndex >= questions.length) {
|
|
257
|
+
return new FunctionResult("I don't have any questions to ask.");
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
const current = questions[questionIndex];
|
|
261
|
+
const instruction = this.generateQuestionInstruction(
|
|
262
|
+
current.question_text ?? '',
|
|
263
|
+
current.confirm === true,
|
|
264
|
+
true,
|
|
265
|
+
);
|
|
266
|
+
|
|
267
|
+
const result = new FunctionResult(instruction);
|
|
268
|
+
result.replaceInHistory('Welcome! Let me ask you a few questions.');
|
|
269
|
+
return result;
|
|
270
|
+
},
|
|
271
|
+
});
|
|
272
|
+
|
|
273
|
+
// Tool: submit_answer
|
|
274
|
+
this.defineTool({
|
|
275
|
+
name: 'submit_answer',
|
|
276
|
+
description: 'Submit an answer to the current question and move to the next one',
|
|
277
|
+
parameters: {
|
|
278
|
+
type: 'object',
|
|
279
|
+
properties: {
|
|
280
|
+
answer: {
|
|
281
|
+
type: 'string',
|
|
282
|
+
description: "The user's answer to the current question",
|
|
283
|
+
},
|
|
284
|
+
},
|
|
285
|
+
},
|
|
286
|
+
handler: (args: Record<string, unknown>, rawData: Record<string, unknown>) => {
|
|
287
|
+
const answer = (args['answer'] as string) ?? '';
|
|
288
|
+
|
|
289
|
+
const globalData = (rawData['global_data'] as Record<string, unknown>) ?? {};
|
|
290
|
+
const questions = (globalData['questions'] as InfoGathererQuestion[]) ?? [];
|
|
291
|
+
const questionIndex = (globalData['question_index'] as number) ?? 0;
|
|
292
|
+
const priorAnswers =
|
|
293
|
+
(globalData['answers'] as Array<{ key_name: string; answer: string }>) ?? [];
|
|
294
|
+
|
|
295
|
+
if (questionIndex >= questions.length) {
|
|
296
|
+
return new FunctionResult('All questions have already been answered.');
|
|
297
|
+
}
|
|
298
|
+
|
|
299
|
+
const current = questions[questionIndex];
|
|
300
|
+
const keyName = current.key_name ?? '';
|
|
301
|
+
const newAnswers = [...priorAnswers, { key_name: keyName, answer }];
|
|
302
|
+
const newIndex = questionIndex + 1;
|
|
303
|
+
|
|
304
|
+
if (newIndex < questions.length) {
|
|
305
|
+
const next = questions[newIndex];
|
|
306
|
+
const instruction = this.generateQuestionInstruction(
|
|
307
|
+
next.question_text ?? '',
|
|
308
|
+
next.confirm === true,
|
|
309
|
+
false,
|
|
310
|
+
);
|
|
311
|
+
const result = new FunctionResult(instruction);
|
|
312
|
+
result.replaceInHistory();
|
|
313
|
+
result.updateGlobalData({ answers: newAnswers, question_index: newIndex });
|
|
314
|
+
return result;
|
|
315
|
+
}
|
|
316
|
+
|
|
317
|
+
const result = new FunctionResult(
|
|
318
|
+
"Thank you! All questions have been answered. You can now summarize the information collected or ask if there's anything else the user would like to discuss.",
|
|
319
|
+
);
|
|
320
|
+
result.replaceInHistory();
|
|
321
|
+
result.updateGlobalData({ answers: newAnswers, question_index: newIndex });
|
|
322
|
+
return result;
|
|
323
|
+
},
|
|
324
|
+
});
|
|
325
|
+
}
|
|
326
|
+
}
|
|
327
|
+
|
|
328
|
+
// ── Factory function ────────────────────────────────────────────────────────
|
|
329
|
+
|
|
330
|
+
/**
|
|
331
|
+
* Factory function that creates and returns a new InfoGathererAgent.
|
|
332
|
+
* @param config - Configuration for the info gatherer agent.
|
|
333
|
+
* @returns A configured InfoGathererAgent instance.
|
|
334
|
+
*/
|
|
335
|
+
export function createInfoGathererAgent(config: InfoGathererConfig = {}): InfoGathererAgent {
|
|
336
|
+
return new InfoGathererAgent(config);
|
|
337
|
+
}
|
|
338
|
+
|
|
339
|
+
export default InfoGathererAgent;
|