@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.
Files changed (325) hide show
  1. package/.github/workflows/publish.yml +27 -0
  2. package/.github/workflows/test.yml +17 -0
  3. package/CLAUDE.md +112 -0
  4. package/README.md +254 -0
  5. package/docs/MIGRATION-2.0.md +81 -0
  6. package/docs/agent-guide.md +869 -0
  7. package/docs/agent_guide.md +1026 -0
  8. package/docs/api-reference.md +2420 -0
  9. package/docs/api_reference.md +1301 -0
  10. package/docs/architecture.md +843 -0
  11. package/docs/cli-guide.md +579 -0
  12. package/docs/cli_guide.md +448 -0
  13. package/docs/cloud_functions_guide.md +474 -0
  14. package/docs/configuration.md +422 -0
  15. package/docs/contexts-guide.md +787 -0
  16. package/docs/contexts_guide.md +511 -0
  17. package/docs/datamap-guide.md +1141 -0
  18. package/docs/datamap_guide.md +595 -0
  19. package/docs/llm_parameters.md +239 -0
  20. package/docs/mcp_gateway_reference.md +648 -0
  21. package/docs/mcp_integration.md +108 -0
  22. package/docs/prefabs-guide.md +800 -0
  23. package/docs/sdk_features.md +477 -0
  24. package/docs/security.md +436 -0
  25. package/docs/serverless-guide.md +513 -0
  26. package/docs/skills-guide.md +857 -0
  27. package/docs/skills-system.md +301 -0
  28. package/docs/skills_parameter_schema.md +392 -0
  29. package/docs/skills_system.md +467 -0
  30. package/docs/swaig-reference.md +1627 -0
  31. package/docs/swaig_reference.md +910 -0
  32. package/docs/swml_service_guide.md +600 -0
  33. package/docs/third_party_skills.md +533 -0
  34. package/docs/web_service.md +677 -0
  35. package/examples/README.md +131 -0
  36. package/examples/advanced-datamap.ts +100 -0
  37. package/examples/advanced-dynamic-config.ts +70 -0
  38. package/examples/auto-vivified.ts +94 -0
  39. package/examples/call-flow.ts +63 -0
  40. package/examples/comprehensive-dynamic.ts +125 -0
  41. package/examples/contexts-steps.ts +65 -0
  42. package/examples/custom-path.ts +45 -0
  43. package/examples/datamap-tools.ts +55 -0
  44. package/examples/datasphere-multi-instance.ts +63 -0
  45. package/examples/datasphere-serverless-env.ts +68 -0
  46. package/examples/datasphere-webhook-env.ts +66 -0
  47. package/examples/datasphere.ts +37 -0
  48. package/examples/declarative.ts +100 -0
  49. package/examples/dynamic-config.ts +54 -0
  50. package/examples/dynamic-info-gatherer.ts +69 -0
  51. package/examples/dynamic-swml-service.ts +67 -0
  52. package/examples/gather-info.ts +71 -0
  53. package/examples/gather-per-question-functions-demo.ts +140 -0
  54. package/examples/joke-agent.ts +34 -0
  55. package/examples/kubernetes-agent.ts +45 -0
  56. package/examples/llm-params.ts +69 -0
  57. package/examples/mcp-agent.ts +84 -0
  58. package/examples/mcp-gateway.ts +35 -0
  59. package/examples/multi-agent.ts +73 -0
  60. package/examples/multi-endpoint.ts +79 -0
  61. package/examples/pom-prompt.ts +71 -0
  62. package/examples/prefab-concierge.ts +47 -0
  63. package/examples/prefab-faq.ts +54 -0
  64. package/examples/prefab-info-gatherer.ts +33 -0
  65. package/examples/prefab-receptionist.ts +36 -0
  66. package/examples/prefab-survey.ts +68 -0
  67. package/examples/record-call.ts +67 -0
  68. package/examples/relay-demo.ts +33 -0
  69. package/examples/room-and-sip.ts +94 -0
  70. package/examples/serverless-lambda.ts +35 -0
  71. package/examples/session-state.ts +83 -0
  72. package/examples/simple-agent.ts +36 -0
  73. package/examples/simple-static.ts +29 -0
  74. package/examples/skills-demo.ts +38 -0
  75. package/examples/step-function-inheritance-demo.ts +124 -0
  76. package/examples/swaig-features.ts +187 -0
  77. package/examples/swml-service-routing.ts +66 -0
  78. package/examples/swml-service.ts +38 -0
  79. package/examples/tap.ts +68 -0
  80. package/examples/verb-methods.ts +45 -0
  81. package/examples/web-search-multi-instance.ts +72 -0
  82. package/examples/web-search.ts +38 -0
  83. package/examples/wikipedia.ts +36 -0
  84. package/livewire/README.md +140 -0
  85. package/livewire/docs/migration-guide.md +228 -0
  86. package/livewire/examples/livewire-basic-agent.ts +74 -0
  87. package/livewire/examples/livewire-handoff.ts +197 -0
  88. package/livewire/examples/livewire-multi-tool.ts +117 -0
  89. package/package.json +38 -0
  90. package/relay/README.md +70 -0
  91. package/relay/RELAY_IMPLEMENTATION_GUIDE.md +1257 -0
  92. package/relay/docs/call-methods.md +474 -0
  93. package/relay/docs/client-reference.md +142 -0
  94. package/relay/docs/events.md +134 -0
  95. package/relay/docs/getting-started.md +134 -0
  96. package/relay/docs/guide.md +306 -0
  97. package/relay/docs/messaging.md +182 -0
  98. package/relay/examples/relay-inbound.ts +66 -0
  99. package/relay/examples/relay-messaging.ts +71 -0
  100. package/relay/examples/relay-outbound.ts +76 -0
  101. package/rest/README.md +95 -0
  102. package/rest/docs/calling.md +273 -0
  103. package/rest/docs/client-reference.md +107 -0
  104. package/rest/docs/compat.md +204 -0
  105. package/rest/docs/fabric.md +183 -0
  106. package/rest/docs/getting-started.md +110 -0
  107. package/rest/docs/guide.md +351 -0
  108. package/rest/docs/namespaces.md +285 -0
  109. package/rest/examples/rest-10dlc-registration.ts +161 -0
  110. package/rest/examples/rest-calling-ivr-and-ai.ts +102 -0
  111. package/rest/examples/rest-calling-play-and-record.ts +91 -0
  112. package/rest/examples/rest-client.ts +65 -0
  113. package/rest/examples/rest-compat-laml.ts +210 -0
  114. package/rest/examples/rest-datasphere-search.ts +82 -0
  115. package/rest/examples/rest-fabric-conferences-and-routing.ts +144 -0
  116. package/rest/examples/rest-fabric-subscribers-and-sip.ts +108 -0
  117. package/rest/examples/rest-fabric-swml-and-callflows.ts +99 -0
  118. package/rest/examples/rest-manage-resources.ts +65 -0
  119. package/rest/examples/rest-phone-number-management.ts +197 -0
  120. package/rest/examples/rest-queues-mfa-and-recordings.ts +143 -0
  121. package/rest/examples/rest-video-rooms.ts +186 -0
  122. package/src/AgentBase.ts +2489 -0
  123. package/src/AgentServer.ts +415 -0
  124. package/src/AuthHandler.ts +256 -0
  125. package/src/ConfigLoader.ts +447 -0
  126. package/src/ContextBuilder.ts +1150 -0
  127. package/src/DataMap.ts +449 -0
  128. package/src/FunctionResult.ts +866 -0
  129. package/src/Logger.ts +337 -0
  130. package/src/PomBuilder.ts +439 -0
  131. package/src/PromptManager.ts +133 -0
  132. package/src/SWMLHandler.ts +298 -0
  133. package/src/SWMLService.ts +717 -0
  134. package/src/SchemaUtils.ts +361 -0
  135. package/src/SecurityUtils.ts +153 -0
  136. package/src/ServerlessAdapter.ts +221 -0
  137. package/src/SessionManager.ts +311 -0
  138. package/src/SslConfig.ts +118 -0
  139. package/src/SwaigFunction.ts +276 -0
  140. package/src/SwmlBuilder.ts +258 -0
  141. package/src/SwmlVerbMethods.generated.ts +234 -0
  142. package/src/TypeInference.ts +181 -0
  143. package/src/WebService.ts +619 -0
  144. package/src/cli/agent-loader.ts +166 -0
  145. package/src/cli/mock-data.ts +111 -0
  146. package/src/cli/swaig-test.ts +452 -0
  147. package/src/generateVerbTypes.ts +322 -0
  148. package/src/index.ts +167 -0
  149. package/src/livewire/index.ts +950 -0
  150. package/src/prefabs/ConciergeAgent.ts +287 -0
  151. package/src/prefabs/FAQBotAgent.ts +384 -0
  152. package/src/prefabs/InfoGathererAgent.ts +339 -0
  153. package/src/prefabs/ReceptionistAgent.ts +366 -0
  154. package/src/prefabs/SurveyAgent.ts +646 -0
  155. package/src/prefabs/index.ts +27 -0
  156. package/src/relay/Action.ts +314 -0
  157. package/src/relay/Call.ts +854 -0
  158. package/src/relay/Deferred.ts +71 -0
  159. package/src/relay/Message.ts +148 -0
  160. package/src/relay/RelayClient.ts +1036 -0
  161. package/src/relay/RelayError.ts +14 -0
  162. package/src/relay/RelayEvent.ts +892 -0
  163. package/src/relay/constants.ts +132 -0
  164. package/src/relay/index.ts +123 -0
  165. package/src/relay/types.ts +149 -0
  166. package/src/rest/HttpClient.ts +103 -0
  167. package/src/rest/RestError.ts +31 -0
  168. package/src/rest/base/BaseResource.ts +19 -0
  169. package/src/rest/base/CrudResource.ts +51 -0
  170. package/src/rest/base/CrudWithAddresses.ts +26 -0
  171. package/src/rest/index.ts +200 -0
  172. package/src/rest/namespaces/addresses.ts +32 -0
  173. package/src/rest/namespaces/calling.ts +187 -0
  174. package/src/rest/namespaces/chat.ts +20 -0
  175. package/src/rest/namespaces/compat.ts +352 -0
  176. package/src/rest/namespaces/datasphere.ts +45 -0
  177. package/src/rest/namespaces/fabric.ts +222 -0
  178. package/src/rest/namespaces/imported-numbers.ts +20 -0
  179. package/src/rest/namespaces/logs.ts +84 -0
  180. package/src/rest/namespaces/lookup.ts +21 -0
  181. package/src/rest/namespaces/mfa.ts +30 -0
  182. package/src/rest/namespaces/number-groups.ts +38 -0
  183. package/src/rest/namespaces/phone-numbers.ts +44 -0
  184. package/src/rest/namespaces/project.ts +36 -0
  185. package/src/rest/namespaces/pubsub.ts +20 -0
  186. package/src/rest/namespaces/queues.ts +33 -0
  187. package/src/rest/namespaces/recordings.ts +28 -0
  188. package/src/rest/namespaces/registry.ts +101 -0
  189. package/src/rest/namespaces/short-codes.ts +28 -0
  190. package/src/rest/namespaces/sip-profile.ts +25 -0
  191. package/src/rest/namespaces/verified-callers.ts +27 -0
  192. package/src/rest/namespaces/video.ts +165 -0
  193. package/src/rest/pagination.ts +84 -0
  194. package/src/rest/types.ts +61 -0
  195. package/src/schema.json +12250 -0
  196. package/src/skills/SkillBase.ts +547 -0
  197. package/src/skills/SkillManager.ts +415 -0
  198. package/src/skills/SkillRegistry.ts +367 -0
  199. package/src/skills/builtin/api_ninjas_trivia.ts +280 -0
  200. package/src/skills/builtin/ask_claude.ts +241 -0
  201. package/src/skills/builtin/claude_skills.ts +978 -0
  202. package/src/skills/builtin/custom_skills.ts +312 -0
  203. package/src/skills/builtin/datasphere.ts +438 -0
  204. package/src/skills/builtin/datasphere_serverless.ts +339 -0
  205. package/src/skills/builtin/datetime.ts +130 -0
  206. package/src/skills/builtin/google_maps.ts +651 -0
  207. package/src/skills/builtin/index.ts +88 -0
  208. package/src/skills/builtin/info_gatherer.ts +405 -0
  209. package/src/skills/builtin/joke.ts +191 -0
  210. package/src/skills/builtin/math.ts +142 -0
  211. package/src/skills/builtin/mcp_gateway.ts +677 -0
  212. package/src/skills/builtin/native_vector_search.ts +901 -0
  213. package/src/skills/builtin/play_background_file.ts +358 -0
  214. package/src/skills/builtin/spider.ts +869 -0
  215. package/src/skills/builtin/swml_transfer.ts +635 -0
  216. package/src/skills/builtin/weather_api.ts +248 -0
  217. package/src/skills/builtin/web_search.ts +1074 -0
  218. package/src/skills/builtin/wikipedia_search.ts +299 -0
  219. package/src/skills/index.ts +12 -0
  220. package/src/types.ts +132 -0
  221. package/tests/AgentBase.test.ts +1093 -0
  222. package/tests/AgentServer.test.ts +126 -0
  223. package/tests/AuthHandler.test.ts +133 -0
  224. package/tests/ConfigLoader.test.ts +151 -0
  225. package/tests/ContextBuilder.test.ts +108 -0
  226. package/tests/DataMap.test.ts +367 -0
  227. package/tests/EphemeralSkillCopy.test.ts +107 -0
  228. package/tests/FunctionResult.test.ts +298 -0
  229. package/tests/GracefulShutdown.test.ts +46 -0
  230. package/tests/Logger.test.ts +420 -0
  231. package/tests/PomBuilder.test.ts +228 -0
  232. package/tests/ProxyDetection.test.ts +228 -0
  233. package/tests/SWMLService.test.ts +320 -0
  234. package/tests/SWMLVerbHandler.test.ts +523 -0
  235. package/tests/SchemaUtils.test.ts +106 -0
  236. package/tests/SchemaUtils.verb.test.ts +206 -0
  237. package/tests/SecurityUtils.test.ts +192 -0
  238. package/tests/ServerlessAdapter.test.ts +222 -0
  239. package/tests/SessionManager.test.ts +257 -0
  240. package/tests/SkillBaseFeatures.test.ts +130 -0
  241. package/tests/SkillMultiInstance.test.ts +102 -0
  242. package/tests/SkillParameterSchemas.test.ts +134 -0
  243. package/tests/SkillRegistrySchema.test.ts +84 -0
  244. package/tests/SslConfig.test.ts +97 -0
  245. package/tests/SwmlBuilder.test.ts +400 -0
  246. package/tests/TypeInference.test.ts +165 -0
  247. package/tests/VerbHandlerRegistry.test.ts +128 -0
  248. package/tests/cli/mock-data.test.ts +113 -0
  249. package/tests/cli/swaig-test.test.ts +108 -0
  250. package/tests/examples.test.ts +194 -0
  251. package/tests/fixtures/scrape-parity/README.md +53 -0
  252. package/tests/fixtures/scrape-parity/expected/01_simple_article.json +5 -0
  253. package/tests/fixtures/scrape-parity/expected/02_class_based_noise.json +5 -0
  254. package/tests/fixtures/scrape-parity/expected/03_nested_containers.json +5 -0
  255. package/tests/fixtures/scrape-parity/expected/04_bare_body.json +5 -0
  256. package/tests/fixtures/scrape-parity/expected/05_malformed.json +5 -0
  257. package/tests/fixtures/scrape-parity/expected/06_multi_class.json +5 -0
  258. package/tests/fixtures/scrape-parity/expected/07_anchor_pattern.json +5 -0
  259. package/tests/fixtures/scrape-parity/expected/08_inline_script.json +5 -0
  260. package/tests/fixtures/scrape-parity/expected/09_whitespace_nbsp.json +5 -0
  261. package/tests/fixtures/scrape-parity/expected/10_entity_unicode.json +5 -0
  262. package/tests/fixtures/scrape-parity/expected/11_cdata_comments.json +5 -0
  263. package/tests/fixtures/scrape-parity/expected/12_deep_nested_removals.json +5 -0
  264. package/tests/fixtures/scrape-parity/html/01_simple_article.html +18 -0
  265. package/tests/fixtures/scrape-parity/html/02_class_based_noise.html +18 -0
  266. package/tests/fixtures/scrape-parity/html/03_nested_containers.html +13 -0
  267. package/tests/fixtures/scrape-parity/html/04_bare_body.html +9 -0
  268. package/tests/fixtures/scrape-parity/html/05_malformed.html +11 -0
  269. package/tests/fixtures/scrape-parity/html/06_multi_class.html +18 -0
  270. package/tests/fixtures/scrape-parity/html/07_anchor_pattern.html +12 -0
  271. package/tests/fixtures/scrape-parity/html/08_inline_script.html +17 -0
  272. package/tests/fixtures/scrape-parity/html/09_whitespace_nbsp.html +21 -0
  273. package/tests/fixtures/scrape-parity/html/10_entity_unicode.html +10 -0
  274. package/tests/fixtures/scrape-parity/html/11_cdata_comments.html +13 -0
  275. package/tests/fixtures/scrape-parity/html/12_deep_nested_removals.html +24 -0
  276. package/tests/fixtures/scrape-parity/python_extract.py +109 -0
  277. package/tests/livewire/livewire.test.ts +780 -0
  278. package/tests/mcp.test.ts +221 -0
  279. package/tests/prefabs/prefabs.test.ts +1093 -0
  280. package/tests/relay/Action.test.ts +392 -0
  281. package/tests/relay/Call.test.ts +535 -0
  282. package/tests/relay/Deferred.test.ts +71 -0
  283. package/tests/relay/Message.test.ts +164 -0
  284. package/tests/relay/RelayClient.test.ts +779 -0
  285. package/tests/relay/RelayEvent.test.ts +463 -0
  286. package/tests/relay/helpers.ts +79 -0
  287. package/tests/rest/HttpClient.test.ts +274 -0
  288. package/tests/rest/RestError.test.ts +53 -0
  289. package/tests/rest/calling.test.ts +156 -0
  290. package/tests/rest/client.test.ts +197 -0
  291. package/tests/rest/compat.test.ts +335 -0
  292. package/tests/rest/datasphere.test.ts +71 -0
  293. package/tests/rest/fabric.test.ts +186 -0
  294. package/tests/rest/helpers.ts +95 -0
  295. package/tests/rest/logs.test.ts +68 -0
  296. package/tests/rest/pagination.test.ts +133 -0
  297. package/tests/rest/registry.test.ts +94 -0
  298. package/tests/rest/relay-rest.test.ts +290 -0
  299. package/tests/rest/video.test.ts +173 -0
  300. package/tests/setup.ts +6 -0
  301. package/tests/skills/SkillBase.test.ts +108 -0
  302. package/tests/skills/SkillManager.test.ts +268 -0
  303. package/tests/skills/SkillRegistry.test.ts +176 -0
  304. package/tests/skills/builtin.test.ts +1472 -0
  305. package/tests/skills/claude-skills.test.ts +54 -0
  306. package/tests/skills/custom-skills.test.ts +53 -0
  307. package/tests/skills/datasphere-serverless.test.ts +70 -0
  308. package/tests/skills/datasphere.test.ts +107 -0
  309. package/tests/skills/datetime.test.ts +101 -0
  310. package/tests/skills/google-maps.test.ts +78 -0
  311. package/tests/skills/info-gatherer.test.ts +411 -0
  312. package/tests/skills/joke.test.ts +81 -0
  313. package/tests/skills/math.test.ts +68 -0
  314. package/tests/skills/mcp-gateway.test.ts +101 -0
  315. package/tests/skills/play-background.test.ts +54 -0
  316. package/tests/skills/spider.test.ts +108 -0
  317. package/tests/skills/swml-transfer.test.ts +178 -0
  318. package/tests/skills/trivia.test.ts +54 -0
  319. package/tests/skills/vector-search.test.ts +135 -0
  320. package/tests/skills/weather-api.test.ts +77 -0
  321. package/tests/skills/web-search-parity.test.ts +59 -0
  322. package/tests/skills/web-search.test.ts +103 -0
  323. package/tests/skills/wikipedia.test.ts +63 -0
  324. package/tsconfig.json +18 -0
  325. package/vitest.config.ts +9 -0
@@ -0,0 +1,511 @@
1
+ # Contexts & Steps Guide
2
+
3
+ Complete guide to building multi-step conversation workflows using the Contexts & Steps system in the SignalWire AI Agents TypeScript SDK.
4
+
5
+ ---
6
+
7
+ ## Table of Contents
8
+
9
+ 1. [Overview](#overview)
10
+ 2. [Creating Contexts](#creating-contexts)
11
+ 3. [Steps](#steps)
12
+ 4. [Step Navigation](#step-navigation)
13
+ 5. [Function Control](#function-control)
14
+ 6. [End States](#end-states)
15
+ 7. [GatherInfo](#gatherinfo)
16
+ 8. [Context Settings](#context-settings)
17
+ 9. [Isolation and Reset](#isolation-and-reset)
18
+ 10. [Fillers](#fillers)
19
+ 11. [Validation](#validation)
20
+ 12. [Real-World Example](#real-world-example)
21
+ 13. [Best Practices](#best-practices)
22
+
23
+ ---
24
+
25
+ ## Overview
26
+
27
+ The Contexts & Steps system provides a **state machine** for structuring multi-step AI conversations. Instead of a single flat prompt, you define a graph of **contexts** that each contain ordered **steps**. The AI navigates through these steps based on completion criteria, enabling complex branching workflows such as customer intake, troubleshooting trees, or multi-department routing.
28
+
29
+ **Key concepts:**
30
+
31
+ - **Context** -- A named group of ordered steps with its own prompt, system prompt, navigation rules, and isolation settings. Think of it as a "page" or "scene" in the conversation.
32
+ - **Step** -- A single stage within a context. Each step has prompt text (raw text or POM sections), completion criteria, function restrictions, and rules about which steps or contexts the AI can move to next.
33
+ - **ContextBuilder** -- The top-level builder that holds all contexts, validates cross-references, and serializes everything to SWML output.
34
+
35
+ ### When to Use Contexts vs Traditional Prompts
36
+
37
+ **Use Contexts and Steps when:**
38
+ - Building multi-step workflows (onboarding, support tickets, applications)
39
+ - Need explicit navigation control between conversation states
40
+ - Want to restrict function access based on conversation stage
41
+ - Building complex customer service or troubleshooting flows
42
+ - Creating guided experiences with clear progression
43
+
44
+ **Use Traditional Prompts when:**
45
+ - Building simple, freeform conversational agents
46
+ - Want maximum flexibility in conversation flow
47
+ - Creating general-purpose assistants
48
+ - Prototyping or building simple proof-of-concepts
49
+
50
+ ### Classes
51
+
52
+ | Class | Role |
53
+ |---|---|
54
+ | `ContextBuilder` | Top-level container; holds and validates all contexts |
55
+ | `Context` | A named context with steps, prompts, fillers, and navigation rules |
56
+ | `Step` | A single step within a context, with text, criteria, and function control |
57
+ | `GatherInfo` | Structured data collection attached to a step |
58
+ | `GatherQuestion` | A single question within a GatherInfo operation |
59
+
60
+ All classes are exported from `@signalwire/sdk`.
61
+
62
+ ---
63
+
64
+ ## Creating Contexts
65
+
66
+ ### Using `agent.defineContexts()`
67
+
68
+ The primary entry point is the `defineContexts()` method on `AgentBase`. It returns a `ContextBuilder` that you use to add contexts.
69
+
70
+ ```typescript
71
+ import { AgentBase } from '@signalwire/sdk';
72
+
73
+ const agent = new AgentBase({ name: 'my-agent' });
74
+
75
+ // Create and get the ContextBuilder
76
+ const cb = agent.defineContexts();
77
+
78
+ // Add contexts to the builder
79
+ const greeting = cb.addContext('greeting');
80
+ const support = cb.addContext('support');
81
+ const farewell = cb.addContext('farewell');
82
+ ```
83
+
84
+ You can also pass an existing `ContextBuilder` instance:
85
+
86
+ ```typescript
87
+ import { ContextBuilder } from '@signalwire/sdk';
88
+
89
+ const cb = new ContextBuilder();
90
+ cb.addContext('default');
91
+ // ... configure ...
92
+
93
+ agent.defineContexts(cb);
94
+ ```
95
+
96
+ ### Using `ContextBuilder.addContext()`
97
+
98
+ ```typescript
99
+ const cb = new ContextBuilder();
100
+
101
+ // Returns the new Context instance for chaining
102
+ const ctx = cb.addContext('intake');
103
+ ```
104
+
105
+ Context names must be unique within a builder. Adding a duplicate name throws an error.
106
+
107
+ ### Retrieving a Context
108
+
109
+ ```typescript
110
+ const ctx = cb.getContext('intake');
111
+ if (ctx) {
112
+ // configure further
113
+ }
114
+ ```
115
+
116
+ ### Single-Context Rule
117
+
118
+ When only one context is defined, it must be named `"default"`. The validation method enforces this:
119
+
120
+ ```typescript
121
+ const cb = new ContextBuilder();
122
+ cb.addContext('default'); // OK -- single context named "default"
123
+
124
+ const cb2 = new ContextBuilder();
125
+ cb2.addContext('intake'); // Will fail validation (single context must be "default")
126
+ ```
127
+
128
+ ---
129
+
130
+ ## Steps
131
+
132
+ Each context contains ordered steps. Steps are added via `context.addStep()`:
133
+
134
+ ```typescript
135
+ const ctx = cb.addContext('intake');
136
+
137
+ const welcome = ctx.addStep('welcome');
138
+ welcome.setText('Welcome! I will help you get set up today.');
139
+
140
+ const info = ctx.addStep('collect_info');
141
+ info.setText('I need to collect some information from you.');
142
+ info.setCriteria('The user has provided their name, email, and phone number.');
143
+ ```
144
+
145
+ ### Step Methods
146
+
147
+ | Method | Description |
148
+ |--------|-------------|
149
+ | `setText(text)` | Set the step's prompt text (raw string). |
150
+ | `addSection(title, opts?)` | Add a POM section to the step. |
151
+ | `setCriteria(criteria)` | Set the completion criteria string. |
152
+ | `setFunctions(fns)` | Restrict which SWAIG functions are available. |
153
+ | `setValidSteps(steps)` | Define which steps the AI can navigate to next. |
154
+ | `setValidContexts(contexts)` | Define which contexts the AI can switch to. |
155
+ | `setEnd(end)` | Mark this step as an end state. |
156
+ | `setGatherInfo(info)` | Attach structured data collection. |
157
+ | `setResetOnEntry(reset)` | Reset step state when re-entered. |
158
+ | `setFillers(fillers)` | Set step-level filler phrases. |
159
+
160
+ ### Step Prompt Text
161
+
162
+ Steps support two modes for prompt content:
163
+
164
+ ```typescript
165
+ // Raw text mode
166
+ const step = ctx.addStep('greeting');
167
+ step.setText('Hello! Welcome to our service.');
168
+
169
+ // POM section mode
170
+ const step2 = ctx.addStep('troubleshoot');
171
+ step2.addSection('Instructions', {
172
+ body: 'Follow these troubleshooting steps:',
173
+ bullets: [
174
+ 'Ask the user to restart the device',
175
+ 'Check if the issue persists',
176
+ 'If yes, escalate to a technician',
177
+ ],
178
+ });
179
+ ```
180
+
181
+ ---
182
+
183
+ ## Step Navigation
184
+
185
+ Control how the AI moves between steps within and across contexts.
186
+
187
+ ### Valid Steps (Within a Context)
188
+
189
+ ```typescript
190
+ const welcome = ctx.addStep('welcome');
191
+ welcome.setValidSteps(['verify_identity', 'skip_to_support']);
192
+
193
+ const verify = ctx.addStep('verify_identity');
194
+ verify.setCriteria('User has provided their account number.');
195
+ verify.setValidSteps(['account_details']);
196
+
197
+ const skip = ctx.addStep('skip_to_support');
198
+ skip.setValidSteps(['account_details']);
199
+ ```
200
+
201
+ ### Valid Contexts (Cross-Context Navigation)
202
+
203
+ ```typescript
204
+ const welcome = ctx.addStep('welcome');
205
+ welcome.setValidContexts(['support', 'billing']);
206
+ ```
207
+
208
+ When the AI determines the step criteria are met (or the user requests a context change), it can navigate to one of the valid contexts.
209
+
210
+ ### Navigation with FunctionResult
211
+
212
+ Tool handlers can trigger navigation programmatically:
213
+
214
+ ```typescript
215
+ import { FunctionResult } from '@signalwire/sdk';
216
+
217
+ // Navigate to a step
218
+ const result = new FunctionResult('Moving to verification.')
219
+ .swmlChangeStep('verify_identity');
220
+
221
+ // Navigate to a context
222
+ const result2 = new FunctionResult('Transferring to billing.')
223
+ .swmlChangeContext('billing', 'initial');
224
+ ```
225
+
226
+ ---
227
+
228
+ ## Function Control
229
+
230
+ Restrict which SWAIG functions are available at each step:
231
+
232
+ ```typescript
233
+ // Only allow these functions during the payment step
234
+ const paymentStep = ctx.addStep('process_payment');
235
+ paymentStep.setFunctions(['validate_card', 'process_payment', 'check_balance']);
236
+
237
+ // No function restrictions (all agent functions available)
238
+ const generalStep = ctx.addStep('general_help');
239
+ // Don't call setFunctions() -- all functions remain available
240
+ ```
241
+
242
+ This is useful for security (preventing payment functions during greeting) and for guiding the AI's behavior (limiting distractions during focused steps).
243
+
244
+ ---
245
+
246
+ ## End States
247
+
248
+ Mark a step as the terminal state of a workflow:
249
+
250
+ ```typescript
251
+ const farewell = ctx.addStep('goodbye');
252
+ farewell.setText('Thank you for calling. Goodbye!');
253
+ farewell.setEnd(true);
254
+ ```
255
+
256
+ When the AI reaches an end step and its criteria are met (or it has no criteria), the conversation flow for that context is considered complete.
257
+
258
+ ---
259
+
260
+ ## GatherInfo
261
+
262
+ `GatherInfo` provides structured data collection at a step. It defines a set of questions the AI asks, with optional validation rules.
263
+
264
+ ```typescript
265
+ import { GatherInfo, GatherQuestion } from '@signalwire/sdk';
266
+
267
+ const gather = new GatherInfo()
268
+ .addQuestion(
269
+ new GatherQuestion('full_name')
270
+ .setQuestion('What is your full name?')
271
+ .setDescription('Customer legal name'),
272
+ )
273
+ .addQuestion(
274
+ new GatherQuestion('email')
275
+ .setQuestion('What is your email address?')
276
+ .setDescription('Primary contact email')
277
+ .setValidation('^[^@]+@[^@]+\\.[^@]+$'),
278
+ )
279
+ .addQuestion(
280
+ new GatherQuestion('phone')
281
+ .setQuestion('What is your phone number?')
282
+ .setDescription('Contact phone number'),
283
+ );
284
+
285
+ const infoStep = ctx.addStep('collect_info');
286
+ infoStep.setText('I need to collect some information from you.');
287
+ infoStep.setGatherInfo(gather);
288
+ ```
289
+
290
+ ### GatherQuestion Methods
291
+
292
+ | Method | Description |
293
+ |--------|-------------|
294
+ | `setQuestion(text)` | The question to ask the user. |
295
+ | `setDescription(desc)` | Description of the expected answer (for the AI). |
296
+ | `setValidation(regex)` | Regex pattern for answer validation. |
297
+
298
+ When a step has a `GatherInfo`, the AI systematically asks each question in order, validates answers against the regex patterns (if provided), and collects all responses before marking the step as complete.
299
+
300
+ ---
301
+
302
+ ## Context Settings
303
+
304
+ ### Context-Level Prompts
305
+
306
+ Each context can have its own prompt text and system prompt:
307
+
308
+ ```typescript
309
+ const support = cb.addContext('support');
310
+ support.setPrompt('You are now helping the user with a technical issue.');
311
+ support.setSystemPrompt('You are a level-2 technical support specialist.');
312
+ ```
313
+
314
+ ### Context Entry Behavior
315
+
316
+ When the AI switches to a new context, the context-level prompt supplements the agent's base prompt. The system prompt (if set) can override aspects of the agent's personality or role for that specific context.
317
+
318
+ ---
319
+
320
+ ## Isolation and Reset
321
+
322
+ ### Reset on Entry
323
+
324
+ Steps can be configured to reset their state when the AI returns to them:
325
+
326
+ ```typescript
327
+ const verifyStep = ctx.addStep('verify');
328
+ verifyStep.setResetOnEntry(true);
329
+ // If the user navigates back to this step, all gathered data and progress are cleared
330
+ ```
331
+
332
+ This is useful for steps that should always start fresh, such as identity verification or payment collection.
333
+
334
+ ---
335
+
336
+ ## Fillers
337
+
338
+ Set filler phrases that the AI speaks while processing or transitioning.
339
+
340
+ ### Context-Level Fillers
341
+
342
+ ```typescript
343
+ const support = cb.addContext('support');
344
+ support.setFillers({
345
+ 'en-US': ['Let me look into that...', 'One moment please...'],
346
+ 'es-MX': ['Un momento por favor...', 'Dejame revisar...'],
347
+ });
348
+ ```
349
+
350
+ ### Step-Level Fillers
351
+
352
+ ```typescript
353
+ const searchStep = ctx.addStep('search');
354
+ searchStep.setFillers({
355
+ 'en-US': ['Searching our database...', 'This may take a moment...'],
356
+ });
357
+ ```
358
+
359
+ Step-level fillers override context-level fillers for that specific step.
360
+
361
+ ---
362
+
363
+ ## Validation
364
+
365
+ Call `validate()` on the `ContextBuilder` to check for configuration errors:
366
+
367
+ ```typescript
368
+ try {
369
+ cb.validate();
370
+ } catch (err) {
371
+ console.error('Context configuration error:', err);
372
+ }
373
+ ```
374
+
375
+ Validation rules:
376
+ - If only one context exists, it must be named `"default"`.
377
+ - Context names must be unique.
378
+ - Step names must be unique within a context.
379
+ - References in `validSteps` must point to existing steps in the same context.
380
+ - References in `validContexts` must point to existing contexts.
381
+
382
+ ---
383
+
384
+ ## Real-World Example
385
+
386
+ ### Customer Support Workflow
387
+
388
+ ```typescript
389
+ import { AgentBase, ContextBuilder, GatherInfo, GatherQuestion, FunctionResult } from '@signalwire/sdk';
390
+
391
+ const agent = new AgentBase({ name: 'support-agent' });
392
+ agent.setPromptText('You are a customer support agent for TechCorp.');
393
+
394
+ const cb = agent.defineContexts();
395
+
396
+ // --- Greeting Context ---
397
+ const greeting = cb.addContext('greeting');
398
+
399
+ const welcome = greeting.addStep('welcome');
400
+ welcome.setText('Welcome to TechCorp support! How can I help you today?');
401
+ welcome.setValidSteps(['identify']);
402
+ welcome.setValidContexts(['technical', 'billing']);
403
+
404
+ const identify = greeting.addStep('identify');
405
+ identify.setText('Let me verify your identity first.');
406
+ identify.setGatherInfo(
407
+ new GatherInfo()
408
+ .addQuestion(
409
+ new GatherQuestion('account_number')
410
+ .setQuestion('What is your account number?')
411
+ .setDescription('8-digit account number')
412
+ .setValidation('^\\d{8}$'),
413
+ )
414
+ .addQuestion(
415
+ new GatherQuestion('name')
416
+ .setQuestion('What is the name on the account?')
417
+ .setDescription('Account holder name'),
418
+ ),
419
+ );
420
+ identify.setCriteria('User has provided a valid account number and name.');
421
+ identify.setFunctions(['verify_account']);
422
+ identify.setValidContexts(['technical', 'billing']);
423
+
424
+ // --- Technical Support Context ---
425
+ const technical = cb.addContext('technical');
426
+ technical.setPrompt('The user needs technical assistance.');
427
+
428
+ const diagnose = technical.addStep('diagnose');
429
+ diagnose.setText('Let me help diagnose your issue.');
430
+ diagnose.addSection('Troubleshooting', {
431
+ body: 'Follow this diagnostic flow:',
432
+ bullets: [
433
+ 'Ask what device or service is affected',
434
+ 'Ask when the issue started',
435
+ 'Check if the user has tried restarting',
436
+ ],
437
+ });
438
+ diagnose.setFunctions(['check_service_status', 'run_diagnostics']);
439
+ diagnose.setValidSteps(['resolve', 'escalate']);
440
+
441
+ const resolve = technical.addStep('resolve');
442
+ resolve.setText('Based on the diagnosis, apply the appropriate fix.');
443
+ resolve.setFunctions(['apply_fix', 'schedule_technician']);
444
+ resolve.setEnd(true);
445
+
446
+ const escalate = technical.addStep('escalate');
447
+ escalate.setText('I will escalate this to our engineering team.');
448
+ escalate.setFunctions(['create_ticket']);
449
+ escalate.setEnd(true);
450
+
451
+ // --- Billing Context ---
452
+ const billing = cb.addContext('billing');
453
+ billing.setPrompt('The user has a billing question.');
454
+
455
+ const reviewBill = billing.addStep('review');
456
+ reviewBill.setText('Let me pull up your billing information.');
457
+ reviewBill.setFunctions(['get_billing_summary', 'get_recent_charges']);
458
+ reviewBill.setValidSteps(['adjust']);
459
+
460
+ const adjustBill = billing.addStep('adjust');
461
+ adjustBill.setText('I can help with billing adjustments.');
462
+ adjustBill.setFunctions(['apply_credit', 'process_refund']);
463
+ adjustBill.setEnd(true);
464
+
465
+ // Define tools
466
+ agent.defineTool({
467
+ name: 'verify_account',
468
+ description: 'Verify a customer account by number and name',
469
+ parameters: {
470
+ account_number: { type: 'string', description: 'Account number' },
471
+ name: { type: 'string', description: 'Account holder name' },
472
+ },
473
+ handler: async (args) => {
474
+ const verified = await verifyAccount(
475
+ args.account_number as string,
476
+ args.name as string,
477
+ );
478
+ if (verified) {
479
+ return new FunctionResult('Account verified successfully.')
480
+ .updateGlobalData({ account_verified: true });
481
+ }
482
+ return new FunctionResult('Account verification failed. Please try again.');
483
+ },
484
+ });
485
+
486
+ agent.defineTool({
487
+ name: 'check_service_status',
488
+ description: 'Check the status of a service',
489
+ parameters: {
490
+ service: { type: 'string', description: 'Service name' },
491
+ },
492
+ handler: async (args) => {
493
+ return new FunctionResult(`Service ${args.service} is operational.`);
494
+ },
495
+ });
496
+
497
+ agent.serve();
498
+ ```
499
+
500
+ ---
501
+
502
+ ## Best Practices
503
+
504
+ 1. **Name contexts and steps descriptively** -- Use names like `"billing_review"` instead of `"step1"`.
505
+ 2. **Always set completion criteria** -- Without criteria, the AI may not know when to advance.
506
+ 3. **Use function restrictions** -- Limit available tools per step to prevent the AI from calling irrelevant functions.
507
+ 4. **Validate before serving** -- Call `cb.validate()` during development to catch configuration errors early.
508
+ 5. **Use GatherInfo for structured collection** -- When you need specific fields from the user, GatherInfo provides better structure than freeform prompting.
509
+ 6. **Set fillers for long operations** -- Filler phrases keep the conversation natural during processing.
510
+ 7. **Design for re-entry** -- Use `setResetOnEntry(true)` on steps that should always start fresh.
511
+ 8. **Limit context depth** -- Keep the context graph shallow; deeply nested contexts can confuse the AI.