SignalWire AI Agents SDK — Porting Checklist Template

Copy this file for your language port and check items off as you go.

The purpose of tests, examples, and docs is to prove complete implementation. If a feature has no test and no example, it's not proven to work. Every feature must have at least one test exercising it.

Target Language: _______________ Start Date: _______________ Python SDK Reference: /path/to/signalwire-agents (the source of truth)

Verification Discipline (read before checking any box)

Agents completing this checklist have historically left gaps by treating ambiguous items as "done" when they were partially done. Every box must be checked only after mechanical verification. The rules below apply to every phase below and are enforced by scripts/audit_checklist.py in the porting-sdk repo (runs in CI).

No item may be checked without a verifiable proof. Proof is one of:
- A passing test whose name you can name.
- A file that exists at a specific path.
- A command that exits 0 (compile, lint, grep-no-match, etc.).
- A string that appears in a specific file at a specific location.
"See OTHER.md" is not permission to skim. If the checklist references another document, read it in full before checking the item.
Counts in this checklist are exact, not floors. "17 skills" means 17 skills, not "at least 17." If the Python reference changes the count, audit_checklist.py fails CI and this file gets updated.
Doc↔code alignment is required. Every method or class referenced in a docs/, rest/docs/, relay/docs/, or examples/ file must exist in the port's source. Phase 13 audits this. A port that ships assign_phone_route in a doc without implementing it fails Phase 13.
"Commit to git" means a named feature branch, not main. Every - [ ] Commit to git means committing on a descriptive feat/<topic> branch (e.g. feat/swml-core, feat/lambda-support, feat/phone-binding-helpers). Direct commits to main fail review.
"No tests skipped" means no tests skipped. pytest -m "not slow", go test -short, rspec --tag ~integration, etc. are not allowed when reporting a phase complete. Run the full suite, 0 failures, 0 skips.
No stubs anywhere. Every artifact in this port — SDK source, examples, skills, CLIs, transports, prefabs — is production code. A function body that returns "would call X in production", "not implemented", hardcoded fake-data shaped to look real, or any value that bypasses the documented upstream call IS A BUG and IS NOT EXEMPT BY ANY TEST. If audit_stubs.py (Phase 13) finds a hit, the port is not done. See PORTING_GUIDE.md → "Production Code Discipline" for the full rule and the small allow-list (optional-extra guards, abstract methods, documented platform restrictions). Tests are NOT allowed to assert stub behavior — a test like assert err.contains("not available") against a transport stub is itself a violation.
Tests prove behavior, not shape. A test that says "the symbol exists" or "the response is non-empty" against a stub passes against canned data. Tests must drive the documented user-visible behavior end-to-end: the function is called, the upstream is contacted (live with credentials, or via a recorded cassette of real upstream output), the parsed response matches what a live caller would see. A mock that removes the requirement that a transport exist at all is wrong — the transport's existence and basic correctness must be tested separately.
Every example runs. Every file in examples/ must do exactly what its docstring says when invoked. audit_examples_run.py (Phase 13) drives each one and asserts the documented behavior. Compile-pass is not acceptance — behavior-pass is.

Phase 1: Foundation

Module/package initialized with git repo (main branch)
Directory structure (see PORTING_GUIDE.md Module Layout)
.gitignore
README.md with quickstart example
CLAUDE.md with development guidance
Dependency file (cpanfile, Gemfile, go.mod, build.gradle, package.json, etc.)
Logging system (levels: debug/info/warn/error, env: SIGNALWIRE_LOG_LEVEL, suppression: SIGNALWIRE_LOG_MODE=off)
Tests: logger creation, level filtering, suppression, env var config
Commit to git

Phase 2: SWML Core

Phase 3: Agent Core

SwaigFunctionResult

Constructor(response, post_process)
SetResponse, SetPostProcess, AddAction, AddActions, ToMap/ToDict
Serialization rules: response always, action only if non-empty, post_process only if true
Exactly 41 action methods documented in SWAIG_FUNCTION_RESULT_REFERENCE.md with exact JSON (read the whole file; count the ### <Method> sections; your port must implement every one). Count is enforced by scripts/audit_checklist.py if the reference doc changes.
Payment helpers: CreatePaymentPrompt, CreatePaymentAction, CreatePaymentParameter
Method chaining on all methods (return self / this / &mut Self)
Tests: construction, serialization, each action category (connect, hangup, say, update_global_data, record_call, toggle_functions, execute_rpc, send_sms, payment helpers), method chaining. Proof: test file exists at the language-idiomatic path, runs clean, covers ≥1 case per method.

SessionManager

HMAC-SHA256 token creation (functionName:callID:expiry, signed, base64)
Token validation (timing-safe comparison, expiry check)
Random 32-byte secret per manager — fail hard if entropy unavailable
Default expiry: 3600 seconds
Tests: token round-trip, wrong function/callID rejected, expired rejected, tampered rejected

DataMap

Fluent builder: New, Purpose/Description, Parameter (with enum), Expression
Webhook, WebhookExpressions, Body, Params, Foreach
Output, FallbackOutput, ErrorKeys, GlobalErrorKeys
ToSwaigFunction serialization
CreateSimpleApiTool helper
CreateExpressionTool helper
Tests: fluent chain, parameters, webhook config, expressions, serialization, helpers

Contexts & Steps

ContextBuilder: AddContext, GetContext, Validate, Reset, ToMap
Context: AddStep, GetStep, RemoveStep, MoveStep, SetInitialStep, all setters, ToMap
Step: all setters (text, sections, criteria, functions, navigation, gather, reset), ToMap
GatherInfo and GatherQuestion
CreateSimpleContext helper
Validation: single context must be "default", initial_step must reference existing step, reserved tool names rejected
AgentBase.ResetContexts() convenience method
Tests: step config, context with steps, gather info, serialization, validation rules, fillers, MoveStep, initial_step, reset

AgentBase

Phase 4: Skills System

Phase 5: Prefab Agents

InfoGathererAgent (questions → start_questions + submit_answer tools)
SurveyAgent (typed questions → validate_response + log_response tools)
ReceptionistAgent (departments → collect_caller_info + transfer_call tools)
FAQBotAgent (FAQs → search_faqs tool with keyword scoring)
ConciergeAgent (venue → check_availability + get_directions tools)
Tests: each constructible, each has expected tools, tool handlers execute
Commit to git

Phase 6: AgentServer

Register/Unregister agents by route
GetAgents/GetAgent
SIP routing (SetupSipRouting, RegisterSipUsername)
Static file serving (with path traversal protection, security headers, MIME types)
Health/ready endpoints
Root index listing agents
Run with HTTP server
Tests: register/unregister, get agents, health endpoint, route dispatch, SIP routing, static file serving
Commit to git

Phase 7: RELAY Client

Phase 8: REST Client

Phone-number binding (required — see phone-binding.md)

Routing an inbound phone number to an SWML webhook, cXML app, AI agent, call flow, etc. is configured on the phone number, not on the Fabric resource. See phone-binding.md for the full model. Every port must ship:

Phase 9: Serverless

First decide per platform: required or optional, based on whether the target language has a first-class runtime on that platform. See PORTING_GUIDE.md § Serverless Support for the capability table and implementation details.

9.0 Per-language capability check

Fill this in before starting the phase:

Target language has first-class AWS Lambda runtime? Yes / No
- If Yes, all Lambda items below are required.
- If No (language needs a custom runtime), Lambda is optional — skip unless there's demand.
Target language has first-class Google Cloud Functions runtime? Yes / No (required if yes)
Target language has first-class Azure Functions runtime? Yes / No (required if yes)
CGI is always trivial — required for all ports.

Reference list of first-class runtimes (update this as AWS/Google/Microsoft add more):

Lambda: Python, Node.js/TypeScript, Java, Ruby, Go, .NET
GCF: Python, Node.js, Java, Ruby, Go, .NET, PHP
Azure: Python, Node.js, Java, PowerShell, .NET

9.1 Execution-mode detection (required for any port implementing any serverless platform)

Idiomatic enum/const for modes: server, cgi, lambda, google_cloud_function, azure_function
Detector reads env vars only (no filesystem, no network)
Detection order: cgi → lambda → gcf → azure → server (Lambda before GCF before Azure — they can overlap in test harnesses)
Env var mapping per PORTING_GUIDE.md § Serverless Support Step 1
Tests: each mode detected via its env var combination, precedence is correct

9.2 AWS Lambda (required iff language has first-class runtime)

9.3 Google Cloud Functions (required iff language has first-class runtime)

Base URL construction per guide (region, project, service name)
SWML_PROXY_URL_BASE takes precedence
Agent route is concatenated into every webhook URL
Handler adapter using the language's Functions Framework
examples/gcf_agent.* exists
Tests: mode detection, base URL, precedence, route-preservation regression, handler smoke test

9.4 Azure Functions (required iff language has first-class runtime)

Base URL construction per guide
SWML_PROXY_URL_BASE takes precedence
Agent route is concatenated into every webhook URL
Handler adapter using the language's Azure Functions library
examples/azure_agent.* exists
Tests: mode detection, base URL, precedence, route-preservation regression, handler smoke test

9.5 CGI (required for all ports)

Mode detection via GATEWAY_INTERFACE
Base URL from HTTPS, HTTP_HOST/SERVER_NAME, SCRIPT_NAME
Tests: mode detection, URL construction, route preservation

9.6 Commit to git

All new serverless code committed on a feature branch
Every test passes — no skips, no --no-verify, no env-var leakage between tests

Phase 10: CLI

Phase 11: Documentation & Examples

Documentation and examples prove the implementation is complete and usable.

The rule is simple: if the Python SDK has a doc or example (except search-related and bedrock-related), the port must have an equivalent in the target language. This is not a suggestion — it's a requirement. Read the Python SDK's docs/, examples/, relay/, and rest/ directories and port every file. Missing docs or examples mean missing proof that the feature works.

Do NOT copy RELAY_IMPLEMENTATION_GUIDE.md into language repos — the canonical copy lives in the porting-sdk repo and is only needed during development.

Top-level docs/ (20 files — ALL from Python SDK except search/bedrock/comparison)

Port every one of these. Each must contain code examples in the target language, not Python.

Skip: search_*.md (4 files), bedrock_agent.md, livekit_comparison.md, pipecat_comparison.md

Top-level relay/ directory (REQUIRED — 9 files)

relay/README.md (API overview, quick start, code examples in target language)
relay/docs/getting-started.md
relay/docs/call-methods.md
relay/docs/events.md
relay/docs/messaging.md
relay/docs/client-reference.md
relay/examples/relay_answer_and_welcome.* (proves: answer, play TTS, hangup)
relay/examples/relay_dial_and_play.* (proves: outbound dial, play, hangup)
relay/examples/relay_ivr_connect.* (proves: collect DTMF, connect to department)

Top-level rest/ directory (REQUIRED — 19 files)

Agent examples/ directory (port ALL from Python except search/bedrock)

Every Python example has a counterpart in the port. The list below is the minimum — if Python has more, port those too. Run ls ~/src/signalwire-python/examples/*.py to get the current list.

Skip: bedrock_.py, search_.py, pgvector_.py, sigmond_.py

Commit to git

Phase 12: Testing Verification

Tests are proof of implementation. The port must test everything the Python SDK tests. Read the Python test files in tests/unit/ and ensure equivalent coverage exists in your port for every tested behavior.

Phase 13: Final Audit (REQUIRED)

Completeness Audit

Symbol-level surface parity (REQUIRED)

The porting-sdk ships python_surface.json — a machine-generated snapshot of every public class, method, and module function in the Python reference. Your port must match this surface, or record each deliberate deviation in PORT_OMISSIONS.md / PORT_ADDITIONS.md.

Your port has a scripts/enumerate_<lang>.* (or equivalent) that walks its source and emits a JSON snapshot in the same shape as python_surface.json — with Python-reference symbol names, not native names. Example: TypeScript's setPromptText is emitted as signalwire.core.agent_base.AgentBase.set_prompt_text. The translation layer is the port's responsibility.
CI step runs diff_port_surface.py --reference porting-sdk/python_surface.json --port-surface <port>.json --omissions PORT_OMISSIONS.md --additions PORT_ADDITIONS.md on every PR. Non-zero exit fails the build.
PORT_OMISSIONS.md at repo root lists every Python-reference symbol the port deliberately does NOT implement, one per line: <fully.qualified.symbol>: <one-line rationale>. The phone-binding work set the precedent: Java and C++ list signalwire.rest.namespaces.fabric.GenericResources.assign_phone_route with rationale "narrow-use legacy API; phone_numbers.set_* is the good path per phone-binding.md".
PORT_ADDITIONS.md at repo root lists every port-only extension (symbols in the port that have no Python-reference equivalent), same format. Reviewers use this to spot drift from the reference.

Doc↔code alignment (REQUIRED — the "Java/C++ phantom API" check)

This section exists because during the phone-binding audit, two ports were found shipping rest/docs/fabric.md that promised assign_phone_route and swml_webhooks.create — methods that had never been implemented in those ports. The checklist let it through because nothing cross-checked doc promises against actual source.

The porting-sdk ships scripts/audit_docs.py — a language-agnostic tool that walks a port's doc and example files, extracts method-call patterns from fenced code blocks and source files, and fails if any reference doesn't resolve in the port's port_surface.json. Every port must wire this into CI.

CI step runs audit_docs.py --root <port-root> --surface port_surface.json --ignore DOC_AUDIT_IGNORE.md. Non-zero exit fails the build.
DOC_AUDIT_IGNORE.md at repo root lists identifiers to skip: external SDK calls (ArgumentParser, Thread), stdlib (json.loads, os.environ.get), HTTP-client basics that aren't in the port's public surface, or intentional future-reference placeholders. Format: one name per line, optional : <rationale>. Skips without rationale are allowed for obvious externals but discouraged; prefer listing why.
Every examples/* file compiles. Required commands per language (exit 0):
- Python: python -m py_compile examples/*.py
- TypeScript: npx tsc --noEmit examples/**/*.ts
- Go: go build ./examples/...
- Java: javac -d /tmp/example-compile examples/**/*.java
- Perl: perl -c examples/*.pl
- Ruby: ruby -c examples/*.rb
- C++: cmake --build build --target examples (or the repo's example target)
If the port deliberately omits a symbol the Python reference ships (e.g. Java and C++ intentionally omit assign_phone_route per the phone-binding spec), record it in PORT_OMISSIONS.md at the port's repo root. One line per omission: <fully-qualified-symbol>: <one-sentence rationale>. The file is checked by Phase 13 CI against the Python reference; un-recorded omissions fail the audit.
If the port adds a symbol that has no Python reference equivalent, record it in PORT_ADDITIONS.md with the same format. Reviewers check that every addition has a justification.

Behavior audit suite (REQUIRED — the "stub on main" check)

This section exists because the audit machinery historically only verified that names existed and tests passed; it did not verify that function bodies actually did the work the names promised. Several ports shipped with relay-client transports stubbed (Stub: production would write to socket), CLI HTTP layers stubbed (HTTP transport not available), /swaig dispatchers silently returning [] for every POST, and skill handlers returning hardcoded fake data. Every layer of the SHAPE audit was happy because the symbols existed and the tests passed — the tests passed because they asserted shape, not behavior.

Eight runnable programs in porting-sdk/scripts/ close the gap. All eight must exit 0 before a port is "complete." The agent fixing a port runs them as the FINAL receipt and pastes the exit codes in the report. The main session re-runs them to verify (agents are not believed without a green program output).

scripts/audit_stubs.py --root <port> exits 0. Greps the port for stub patterns (commented stubs like // stub: in production..., silent canned-data stubs whose params are all prefixed _ and body is one literal return, feature gates whose feature isn't declared, panicking "not implemented" macros, etc.). Hits must be fixed OR recorded with rationale in port's INTENTIONAL_NON_IMPLEMENTATION.md.
scripts/audit_http_swml.py --root <port> exits 0. For each port's example services, binds a real socket, asserts GET <route> returns a valid SWML doc, asserts POST <route>/swaig with {"function":"NAME","argument":{"parsed":[{...}]}} actually invokes the registered handler and returns its real response (not canned []). Catches dispatcher stubs.
scripts/audit_relay_handshake.py --root <port> exits 0. Stands up a local WS fixture on 127.0.0.1:0 that speaks JSON-RPC 2.0 and the signalwire.connect handshake. Drives the port's RELAY client at it. Asserts WSS upgrade arrives, signalwire.connect request is sent, auth response is parsed, contexts subscribe, an event the fixture pushes is dispatched to the client's callback. Catches stub WS transports (// Stub: production would open WSS...).
scripts/audit_rest_transport.py --root <port> exits 0. Stands up a local HTTP fixture on 127.0.0.1:0. Drives every REST namespace's documented operations against it. Asserts the wire request shape (method, path, headers, query params, body) matches the documented contract, and the parsed response matches a recorded real-shape response. Proves transport + serialization, NOT third-party reachability.
scripts/audit_skills_dispatch.py --root <port> exits 0. For each skill that names an upstream service (Google CSE, Wikipedia, DataSphere, MCP gateway, etc.), drives the skill against a local HTTP fixture (no live credentials required) and asserts the skill's handler issued a real outbound HTTP request with the documented shape AND parsed a recorded response correctly. A skill whose handler returns canned data without contacting the fixture fails. Live testing against real upstreams is gated separately by an env var like SWSDK_LIVE_TESTS=1; the fixture-based audit is the always-on baseline.
scripts/audit_test_parity.py --root <port> exits 0. Every Python test (minus skip list) has a behavior-equivalent in the port. Walks Python's tests/ and the port's tests, maps by target symbol, fails on missing tests AND on tests whose body doesn't actually drive the symbol.
scripts/audit_example_parity.py --root <port> exits 0. Every Python example (minus skip list) has a port-equivalent with the same documented contract.
scripts/audit_no_cheat_tests.py --root <port> exits 0. No assert true / expect(true).toBe(true), no empty / pass-bodied tests, no no-assertion tests, no tests that mock the very transport they exist to verify, no tests that only assert nullness (assertNotNull(result)) without checking response content. Allow-list in port's INTENTIONAL_THIN_TESTS.md for legit thin tests with rationale.

These eight audits answer "do the named things actually do what they claim?" The Layer A/B/C audits below answer "do the named things exist?" Both are required.

Security Audit

Read all source code and review the full implementation for security issues. The items below are known vulnerabilities found in prior ports — check each with a concrete grep or test, not a skim:

FilesExpand file tree

CHECKLIST.md

Latest commit

History