Enhance AI documentation with best practices and tool calling guidance - #490
Draft
Devon-White wants to merge 51 commits into
Draft
Enhance AI documentation with best practices and tool calling guidance#490Devon-White wants to merge 51 commits into
Devon-White wants to merge 51 commits into
Conversation
- Added "max-toc-depth" to best practices and index pages for improved navigation. - Expanded best practices section with insights on over-prompting and examples. - Introduced a new "Next steps" section in best practices and index pages linking to relevant resources. - Updated references to tool calling in various documents to ensure consistency and clarity. - Created a comprehensive guide on tool calling, detailing its importance and implementation in AI agents. - Improved descriptions and links in existing AI documentation for better user understanding.
Contributor
…SDK across multiple guides
…on methods and no-code options
- Replace ai-agent.svg with light/dark ai-agent-flow SVG pair using the CSS-only .light-only/.dark-only pattern in styles.css - Convert capabilities build-methods prose to a CardGroup - Use docstring-driven tool definition in the drive-thru example so the inferred schema keeps the parameter description; add required to the SWML variant for parity - Trim aphorisms: reword menu-liability line, drop the duplicated suggestion/constraint line from best practices - Fix stale /docs/swml/reference/ai link in the overview use cases
- Updated the "No-code agent" guide to enhance clarity and improve structure. - Removed unnecessary elements and streamlined instructions for creating AI agents. - Revised "Best practices for creating a SignalWire AI agent" to remove author metadata and improve focus on content. - Enhanced "Prompt engineering best practices" with clearer language and better organization. - Improved "Prompt engineering" overview to emphasize clarity and structure in prompt writing. - Clarified the "Where to apply prompt engineering" guide, ensuring better understanding of prompt areas. - Revised "AI overview" to emphasize the capabilities of SignalWire AI and streamline the quickstart instructions. - Updated "Getting started" documentation for better flow and clarity, including clearer distinctions between SDKs and approaches.
…ngineering and capabilities
Contributor
|
Requested by: Devon White |
Single theme-aware AI flow diagram SVG
… emphasize coding obligations for AI calls
Collaborator
|
reviewed the entirety of the Platform section and believe outside of what we had talked about this looks g2g! |
…ool calling guide
…za example The request field list came from the SWML reference snippet unchanged, and promoting it onto the tool calling guide as "complete" put it next to the OpenAPI webhook describing the same payload with different contents. Verified the list against the post_data construction in mod_openai actions.c: - purpose is not a request field. The engine reads functions.purpose (or its replacement, functions.description) from the config and sends it as description. Documented description; dropped purpose. - Added the eight fields that were missing: conversation_id, meta_data_token, SWMLCall, call_log, raw_call_log, fatal_error, error_reason, description. - argument.parsed is an array, not an object; argument_desc is always an object when the function declares parameters, and absent for the legacy string form. - Split the list into always-present and conditional, and said what each condition is, since more than half the payload is conditional. Retitled the accordions off the completeness claim so the OpenAPI webhook stays the contract of record. Also fixed three things the guardrails rewrite left inconsistent: - The pizza prompt told the agent to quote sizes and toppings only from get_menu while its own knowledge base listed them. Only prices were ever absent from that knowledge base, so the guardrails now cover prices, totals, discounts, and substitutions, and the response guideline that promised "clear pricing information" defers to place_order. - The diagram's discount turn claimed a priced order before one existed. - meta_data is declared in the SWML document or written by set_meta_data and scoped by meta_data_token; it is not call-global and not set through the APIs at call creation. Framed the prompt impact diagram to match the other two.
The SWAIG snippets on the amazon_bedrock reference pages described the `ai` agent's payload. Bedrock builds its request on a separate code path (bedrock.c:4333 -> bedrock_get_post_data(bs, FALSE, "agent.function")), so most of what those pages claimed was wrong. Omit<> can't express the difference: it is not a subset. Against the ai payload Bedrock drops 10 fields, adds 10, and changes 6 more, including two whose documented constant values differ and a nested object that loses a member. The sidecar webhook already sets the precedent of a separate model for a divergent SWAIG payload, so Bedrock gets one too. Spec: - Added BedrockSwaigToolWebhookPayload and registered it on the Calls namespace. content_type is text/json, content_disposition agent.function, plus conversation_type, action, caller_id, the call/agent timestamps (microseconds) and times; argument has no substituted; no version, description, or argument_desc. Docs: - New _bedrock-swaig-request-fields, _bedrock-swaig-actions, and _bedrock-web-hook-url snippets, and pointed the three Bedrock pages at them. - Bedrock accepts only 6 actions (SWML, transfer, set/unset_global_data, set/unset_meta_data) against the ai path's 17, and its transfer is a boolean modifier on SWML rather than a standalone action with a destination. Verified DataMap output actions run through the same restricted handler, so that page was relisting ai-only actions too. - Unrecognized action keys are silently ignored, which is worth stating: an ai-shaped reply fails quietly on Bedrock. Two corrections to the previous commit, both found while checking Bedrock: - meta_data_token and meta_data are not conditional on either path. The engine falls back to a derived token when you don't set one, so both are always sent to a webhook-backed function. Moved them and described the fallback. - The ai request example still showed purpose; the wire field is description.
Webhooks only render if they are listed in apis.yml; without the entry the page 404s even though the operation is in the OpenAPI document.
- Updated AI SWAIG function documentation to clarify request and response formats, including examples for webhook payloads. - Revised Bedrock SWAIG function documentation to streamline function definitions and clarify webhook interactions. - Enhanced TypeSpec models for SWAIG webhook payloads, adding detailed descriptions and examples for better clarity. - Removed deprecated fields from SWAIG models and documentation, ensuring alignment with current API specifications. - Introduced new conventions for TypeSpec documentation and editing practices to maintain consistency and accuracy across specs.
Reframe prompt guardrails, document the SWAIG wire protocol, and replace AI diagrams with themed SVGs
…n references and formatting improvements
…s section with best practices
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Restructures the AI platform section around tool calling and production best practices. Closes #489.
What changed
/ai/tool-calling) — the mental model (the AI agent is the front end, your code owns the business logic), how a SWAIG function works, a complete order-status agent in SWML and the Python Server SDK, and five patterns for reliable SWAIG functions./ai/best-practices) — restructured around the prompt/code split, writing for real-time voice (end-pointing and turnaround), speech-recognition hints, testing and monitoring with post-prompt reports, and TCPA compliance, ending with a complete worked example that shows the request/response exchange..light-only/.dark-onlyrules instyles.css)./docs/swml/reference/aipaths, standardized "Next steps" sections.ai-agent.svg.