@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,474 @@
1
+ # SignalWire AI Agents - Cloud Functions Deployment Guide
2
+
3
+ This guide covers deploying SignalWire AI Agents to Google Cloud Functions and Azure Functions.
4
+
5
+ ## Overview
6
+
7
+ SignalWire AI Agents now support deployment to major cloud function platforms:
8
+
9
+ - **Google Cloud Functions** - Serverless compute platform on Google Cloud
10
+ - **Azure Functions** - Serverless compute service on Microsoft Azure
11
+ - **AWS Lambda** - Already supported (see existing documentation)
12
+
13
+ ## Google Cloud Functions
14
+
15
+ ### Environment Detection
16
+
17
+ The agent automatically detects Google Cloud Functions environment using these variables:
18
+ - `FUNCTION_TARGET` - The function entry point
19
+ - `K_SERVICE` - Knative service name (Cloud Run/Functions)
20
+ - `GOOGLE_CLOUD_PROJECT` - Google Cloud project ID
21
+
22
+ ### Deployment Steps
23
+
24
+ 1. **Create your agent file** (`main.py`):
25
+ ```python
26
+ import functions_framework
27
+ from your_agent_module import YourAgent
28
+
29
+ # Create agent instance
30
+ agent = YourAgent(
31
+ name="my-agent",
32
+ # Configure your agent parameters
33
+ )
34
+
35
+ @functions_framework.http
36
+ def agent_handler(request):
37
+ """HTTP Cloud Function entry point"""
38
+ return agent.handle_serverless_request(event=request)
39
+ ```
40
+
41
+ 2. **Create requirements.txt**:
42
+ ```
43
+ functions-framework==3.*
44
+ @signalwire/sdk
45
+ # Add your other dependencies
46
+ ```
47
+
48
+ 3. **Deploy using gcloud**:
49
+ ```bash
50
+ gcloud functions deploy my-agent \
51
+ --runtime python39 \
52
+ --trigger-http \
53
+ --entry-point agent_handler \
54
+ --allow-unauthenticated
55
+ ```
56
+
57
+ ### Environment Variables
58
+
59
+ Set these environment variables for your function:
60
+
61
+ ```bash
62
+ # SignalWire credentials
63
+ export SIGNALWIRE_PROJECT_ID="your-project-id"
64
+ export SIGNALWIRE_TOKEN="your-token"
65
+
66
+ # Agent configuration
67
+ export AGENT_USERNAME="your-username"
68
+ export AGENT_PASSWORD="your-password"
69
+
70
+ # Optional: Custom region/project settings
71
+ export FUNCTION_REGION="us-central1"
72
+ export GOOGLE_CLOUD_PROJECT="your-project-id"
73
+ ```
74
+
75
+ ### URL Format
76
+
77
+ Google Cloud Functions URLs follow this pattern:
78
+ ```
79
+ https://{region}-{project-id}.cloudfunctions.net/{function-name}
80
+ ```
81
+
82
+ With authentication:
83
+ ```
84
+ https://username:password@{region}-{project-id}.cloudfunctions.net/{function-name}
85
+ ```
86
+
87
+ ## Azure Functions
88
+
89
+ ### Environment Detection
90
+
91
+ The agent automatically detects Azure Functions environment using these variables:
92
+ - `AZURE_FUNCTIONS_ENVIRONMENT` - Azure Functions runtime environment
93
+ - `FUNCTIONS_WORKER_RUNTIME` - Runtime language (python, node, etc.)
94
+ - `AzureWebJobsStorage` - Azure storage connection string
95
+
96
+ ### Deployment Steps
97
+
98
+ 1. **Create your function app structure**:
99
+ ```
100
+ my-agent-function/
101
+ ├── __init__.py
102
+ ├── function.json
103
+ └── requirements.txt
104
+ ```
105
+
106
+ 2. **Create `__init__.py`**:
107
+ ```python
108
+ import azure.functions as func
109
+ from your_agent_module import YourAgent
110
+
111
+ # Create agent instance
112
+ agent = YourAgent(
113
+ name="my-agent",
114
+ # Configure your agent parameters
115
+ )
116
+
117
+ def main(req: func.HttpRequest) -> func.HttpResponse:
118
+ """Azure Function entry point"""
119
+ return agent.handle_serverless_request(event=req)
120
+ ```
121
+
122
+ 3. **Create `function.json`**:
123
+ ```json
124
+ {
125
+ "scriptFile": "__init__.py",
126
+ "bindings": [
127
+ {
128
+ "authLevel": "anonymous",
129
+ "type": "httpTrigger",
130
+ "direction": "in",
131
+ "name": "req",
132
+ "methods": ["get", "post"]
133
+ },
134
+ {
135
+ "type": "http",
136
+ "direction": "out",
137
+ "name": "$return"
138
+ }
139
+ ]
140
+ }
141
+ ```
142
+
143
+ 4. **Create `requirements.txt`**:
144
+ ```
145
+ azure-functions
146
+ @signalwire/sdk
147
+ # Add your other dependencies
148
+ ```
149
+
150
+ 5. **Deploy using Azure CLI**:
151
+ ```bash
152
+ # Create function app
153
+ az functionapp create \
154
+ --resource-group myResourceGroup \
155
+ --consumption-plan-location westus \
156
+ --runtime python \
157
+ --runtime-version 3.9 \
158
+ --functions-version 4 \
159
+ --name my-agent-function \
160
+ --storage-account mystorageaccount
161
+
162
+ # Deploy code
163
+ func azure functionapp publish my-agent-function
164
+ ```
165
+
166
+ ### Environment Variables
167
+
168
+ Set these in your Azure Function App settings:
169
+
170
+ ```bash
171
+ # SignalWire credentials
172
+ SIGNALWIRE_PROJECT_ID="your-project-id"
173
+ SIGNALWIRE_TOKEN="your-token"
174
+
175
+ # Agent configuration
176
+ AGENT_USERNAME="your-username"
177
+ AGENT_PASSWORD="your-password"
178
+
179
+ # Azure-specific (usually auto-set)
180
+ AZURE_FUNCTIONS_ENVIRONMENT="Development"
181
+ WEBSITE_SITE_NAME="my-agent-function"
182
+ ```
183
+
184
+ ### URL Format
185
+
186
+ Azure Functions URLs follow this pattern:
187
+ ```
188
+ https://{function-app-name}.azurewebsites.net/api/{function-name}
189
+ ```
190
+
191
+ With authentication:
192
+ ```
193
+ https://username:password@{function-app-name}.azurewebsites.net/api/{function-name}
194
+ ```
195
+
196
+ ## Authentication
197
+
198
+ Both platforms support HTTP Basic Authentication:
199
+
200
+ ### Automatic Authentication
201
+ The agent automatically validates credentials in cloud function environments:
202
+
203
+ ```python
204
+ agent = YourAgent(
205
+ name="my-agent",
206
+ username="your-username",
207
+ password="your-password"
208
+ )
209
+ ```
210
+
211
+ ### Authentication Flow
212
+ 1. Client sends request with `Authorization: Basic <credentials>` header
213
+ 2. Agent validates credentials against configured username/password
214
+ 3. If invalid, returns 401 with `WWW-Authenticate` header
215
+ 4. If valid, processes the request normally
216
+
217
+ ## Testing
218
+
219
+ ### SignalWire Agent Testing Tool
220
+
221
+ The SignalWire AI Agents SDK includes a testing tool (`swaig-test`) that can simulate cloud function environments for comprehensive testing before deployment.
222
+
223
+ #### Cloud Function Environment Simulation
224
+
225
+ **Google Cloud Functions:**
226
+ ```bash
227
+ # Test SWML generation in GCP environment
228
+ swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project my-project --dump-swml
229
+
230
+ # Test function execution
231
+ swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project my-project --exec my_function --param value
232
+
233
+ # With custom region and service
234
+ swaig-test examples/my_agent.py --simulate-serverless cloud_function \
235
+ --gcp-project my-project \
236
+ --gcp-region us-west1 \
237
+ --gcp-service my-service \
238
+ --dump-swml
239
+ ```
240
+
241
+ **Azure Functions:**
242
+ ```bash
243
+ # Test SWML generation in Azure environment
244
+ swaig-test examples/my_agent.py --simulate-serverless azure_function --dump-swml
245
+
246
+ # Test function execution
247
+ swaig-test examples/my_agent.py --simulate-serverless azure_function --exec my_function --param value
248
+
249
+ # With custom environment and URL
250
+ swaig-test examples/my_agent.py --simulate-serverless azure_function \
251
+ --azure-env Production \
252
+ --azure-function-url https://myapp.azurewebsites.net/api/myfunction \
253
+ --dump-swml
254
+ ```
255
+
256
+ #### Environment Variable Testing
257
+
258
+ Test with custom environment variables:
259
+ ```bash
260
+ # Set individual environment variables
261
+ swaig-test examples/my_agent.py --simulate-serverless cloud_function \
262
+ --env GOOGLE_CLOUD_PROJECT=my-project \
263
+ --env DEBUG=1 \
264
+ --exec my_function
265
+
266
+ # Load from environment file
267
+ swaig-test examples/my_agent.py --simulate-serverless azure_function \
268
+ --env-file production.env \
269
+ --dump-swml
270
+ ```
271
+
272
+ #### Authentication Testing
273
+
274
+ Test authentication in cloud function environments:
275
+ ```bash
276
+ # Test with authentication (uses agent's configured credentials)
277
+ swaig-test examples/my_agent.py --simulate-serverless cloud_function \
278
+ --gcp-project my-project \
279
+ --dump-swml --verbose
280
+
281
+ # The tool automatically tests:
282
+ # - Basic auth credential embedding in URLs
283
+ # - Authentication challenge responses
284
+ # - Platform-specific auth handling
285
+ ```
286
+
287
+ #### URL Generation Testing
288
+
289
+ Verify that URLs are generated correctly for each platform:
290
+ ```bash
291
+ # Check URL generation with verbose output
292
+ swaig-test examples/my_agent.py --simulate-serverless cloud_function \
293
+ --gcp-project my-project \
294
+ --dump-swml --verbose
295
+
296
+ # Extract webhook URLs from SWML
297
+ swaig-test examples/my_agent.py --simulate-serverless azure_function \
298
+ --dump-swml --raw | jq '.sections.main[1].ai.SWAIG.functions[].web_hook_url'
299
+ ```
300
+
301
+ #### Available Testing Options
302
+
303
+ **Platform Selection:**
304
+ - `--simulate-serverless cloud_function` - Google Cloud Functions
305
+ - `--simulate-serverless azure_function` - Azure Functions
306
+ - `--simulate-serverless lambda` - AWS Lambda
307
+ - `--simulate-serverless cgi` - CGI environment
308
+
309
+ **Google Cloud Platform Options:**
310
+ - `--gcp-project PROJECT_ID` - Set Google Cloud project ID
311
+ - `--gcp-region REGION` - Set Google Cloud region (default: us-central1)
312
+ - `--gcp-service SERVICE` - Set service name
313
+ - `--gcp-function-url URL` - Override function URL
314
+
315
+ **Azure Functions Options:**
316
+ - `--azure-env ENVIRONMENT` - Set Azure environment (default: Development)
317
+ - `--azure-function-url URL` - Override Azure Function URL
318
+
319
+ **Environment Variables:**
320
+ - `--env KEY=value` - Set individual environment variables
321
+ - `--env-file FILE` - Load environment variables from file
322
+
323
+ **Output Options:**
324
+ - `--dump-swml` - Generate and display SWML document
325
+ - `--verbose` - Show detailed information
326
+ - `--raw` - Output raw JSON (useful for piping to jq)
327
+
328
+ #### Complete Testing Workflow
329
+
330
+ ```bash
331
+ # 1. List available agents and tools
332
+ swaig-test examples/my_agent.py --list-agents
333
+ swaig-test examples/my_agent.py --list-tools
334
+
335
+ # 2. Test SWML generation for each platform
336
+ swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project test-project --dump-swml
337
+ swaig-test examples/my_agent.py --simulate-serverless azure_function --dump-swml
338
+
339
+ # 3. Test specific function execution
340
+ swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project test-project --exec search_knowledge --query "test"
341
+
342
+ # 4. Test with production-like environment
343
+ swaig-test examples/my_agent.py --simulate-serverless azure_function --env-file production.env --exec my_function --param value
344
+
345
+ # 5. Verify authentication and URL generation
346
+ swaig-test examples/my_agent.py --simulate-serverless cloud_function --gcp-project prod-project --dump-swml --verbose
347
+ ```
348
+
349
+ ### Local Testing
350
+
351
+ **Google Cloud Functions:**
352
+ ```bash
353
+ # Install Functions Framework
354
+ pip install functions-framework
355
+
356
+ # Run locally
357
+ functions-framework --target=agent_handler --debug
358
+ ```
359
+
360
+ **Azure Functions:**
361
+ ```bash
362
+ # Install Azure Functions Core Tools
363
+ npm install -g azure-functions-core-tools@4
364
+
365
+ # Run locally
366
+ func start
367
+ ```
368
+
369
+ ### Testing Authentication
370
+
371
+ ```bash
372
+ # Test without auth (should return 401)
373
+ curl https://your-function-url/
374
+
375
+ # Test with valid auth
376
+ curl -u username:password https://your-function-url/
377
+
378
+ # Test SWAIG function call
379
+ curl -u username:password \
380
+ -H "Content-Type: application/json" \
381
+ -d '{"call_id": "test", "argument": {"parsed": [{"param": "value"}]}}' \
382
+ https://your-function-url/your_function_name
383
+ ```
384
+
385
+ ## Best Practices
386
+
387
+ ### Performance
388
+ - Use connection pooling for database connections
389
+ - Implement proper caching strategies
390
+ - Minimize cold start times with smaller deployment packages
391
+
392
+ ### Security
393
+ - Always use HTTPS endpoints
394
+ - Implement proper authentication
395
+ - Use environment variables for sensitive data
396
+ - Consider using cloud-native secret management
397
+
398
+ ### Monitoring
399
+ - Enable cloud platform logging
400
+ - Monitor function execution times
401
+ - Set up alerts for errors and timeouts
402
+ - Use distributed tracing for complex workflows
403
+
404
+ ### Cost Optimization
405
+ - Right-size memory allocation
406
+ - Implement proper timeout settings
407
+ - Use reserved capacity for predictable workloads
408
+ - Monitor and optimize function execution patterns
409
+
410
+ ## Troubleshooting
411
+
412
+ ### Common Issues
413
+
414
+ **Environment Detection:**
415
+ ```python
416
+ # Check detected mode
417
+ from signalwire_agents.core.logging_config import get_execution_mode
418
+ print(f"Detected mode: {get_execution_mode()}")
419
+ ```
420
+
421
+ **URL Generation:**
422
+ ```python
423
+ # Check generated URLs
424
+ agent = YourAgent(name="test")
425
+ print(f"Base URL: {agent.get_full_url()}")
426
+ print(f"Auth URL: {agent.get_full_url(include_auth=True)}")
427
+ ```
428
+
429
+ **Authentication Issues:**
430
+ - Verify username/password are set correctly
431
+ - Check that Authorization header is being sent
432
+ - Ensure credentials match exactly (case-sensitive)
433
+
434
+ ### Debugging
435
+
436
+ Enable debug logging:
437
+ ```python
438
+ import logging
439
+ logging.basicConfig(level=logging.DEBUG)
440
+ ```
441
+
442
+ Check environment variables:
443
+ ```python
444
+ import os
445
+ for key, value in os.environ.items():
446
+ if 'FUNCTION' in key or 'AZURE' in key or 'GOOGLE' in key:
447
+ print(f"{key}: {value}")
448
+ ```
449
+
450
+ ## Migration from Other Platforms
451
+
452
+ ### From AWS Lambda
453
+ - Update environment variable names
454
+ - Modify request/response handling if needed
455
+ - Update deployment scripts
456
+
457
+ ### From Traditional Servers
458
+ - Add cloud function entry point
459
+ - Configure environment variables
460
+ - Update URL generation logic
461
+ - Test authentication flow
462
+
463
+ ## Examples
464
+
465
+ See `examples/lambda_agent.py` for a complete AWS Lambda deployment example.
466
+
467
+ ## Support
468
+
469
+ For issues specific to cloud function deployment:
470
+ 1. Check the troubleshooting section above
471
+ 2. Verify environment variables are set correctly
472
+ 3. Test authentication flow manually
473
+ 4. Check cloud platform logs for detailed error messages
474
+ 5. Refer to platform-specific documentation for deployment issues