Update to Twilio Developer Kit

{
  "name": "twilio-enterprise-knowledge",
  "description": "Add knowledge retrieval to AI agents using Twilio's Enterprise Knowledge product. Enterprise Knowledge is a centralized, searchable repository of your organization's documents, websites, and content — FAQs, support policies, warranty terms, product catalogs. Current models don't have access to how you run your business today. Enterprise Knowledge gives agents a way to query this repository during a conversation and ground their responses in your actual approved source material. This skill covers provisioning a Knowledge Base and uploading knowledge sources from web URLs, PDFs, and raw text, and running semantic search to retrieve relevant chunks at runtime. Enterprise Knowledge is shared across your organization — it captures what your organization knows and how it is meant to run. It is distinct from Conversation Memory (twilio-customer-memory), which is scoped to individual end-customers and captures what you know about a specific person. The two are designed to be combined: enterprise content for business practices, customer memory for personalization.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 235
    }
  ],
  "skill_md_contents": "---\nname: twilio-enterprise-knowledge\ndescription: >\n  Add knowledge retrieval to AI agents using Twilio's Enterprise Knowledge\n  product. Enterprise Knowledge is a centralized, searchable repository of your\n  organization's documents, websites, and content — FAQs, support policies,\n  warranty terms, product catalogs. Current models don't have access to how you\n  run your business today. Enterprise Knowledge gives agents a way to query this\n  repository during a conversation and ground their responses in your actual\n  approved source material. This skill covers provisioning a Knowledge Base and\n  uploading knowledge sources from web URLs, PDFs, and raw text, and running\n  semantic search to retrieve relevant chunks at runtime. Enterprise Knowledge is\n  shared across your organization — it captures what your organization knows and\n  how it is meant to run. It is distinct from Conversation Memory\n  (twilio-customer-memory), which is scoped to individual end-customers and\n  captures what you know about a specific person. The two are designed to be\n  combined: enterprise content for business practices, customer memory for\n  personalization.\n---\n\n## Overview\n\nEnterprise Knowledge gives AI and human agents access to your organization's actual source material during a conversation — FAQs, warranty policies, support scripts, product catalogs. Models trained on general data don't know how your business operates today; Enterprise Knowledge closes that gap by letting agents query a searchable repository of your approved content and inject accurate, up-to-date answers rather than hallucinated ones.\n\n```\nYour content (web/PDF/text) → Knowledge Base → Indexed chunks\nAgent query → Search → Ranked chunks → Inject into LLM prompt\n```\n\nEnterprise Knowledge is shared across your organization and captures institutional content: how your products work, what your policies say, what your agents are supposed to do. It is distinct from Conversation Memory, which is scoped to individual end-customers. The two are designed to be combined — enterprise content for accuracy and business practices, customer memory for personalization.\n\n**Auth: Basic Auth** — `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN`.\n\n---\n\n## Prerequisites\n\n- Twilio account with Enterprise Knowledge access (requires enablement)\n  — New to Twilio? See `twilio-account-setup`\n- `TWILIO_ACCOUNT_SID` and `TWILIO_AUTH_TOKEN` — see `twilio-iam-auth-setup`\n\n---\n\n## Quickstart\n\n### Step 1 — Create a Knowledge Base\n\nKnowledge Bases are containers for knowledge sources. Creation is async — returns 202, poll the `Location` header until `status: ACTIVE`.\n\n**Python**\n```python\nimport os, requests, time\n\naccount_sid = os.environ[\"TWILIO_ACCOUNT_SID\"]\nauth_token = os.environ[\"TWILIO_AUTH_TOKEN\"]\n\nres = requests.post(\n    \"https://memory.twilio.com/v1/ControlPlane/KnowledgeBases\",\n    auth=(account_sid, auth_token),\n    json={\n        \"displayName\": \"product-docs\",          # alphanumeric + hyphens only\n        \"description\": \"Product documentation for customer support agents\"\n    }\n)\n\noperation_url = res.headers[\"Location\"]\n\n# Poll until ready\nwhile True:\n    kb = requests.get(operation_url, auth=(account_sid, auth_token)).json()\n    if kb.get(\"status\") == \"ACTIVE\":\n        kb_id = kb[\"id\"]\n        break\n    if kb.get(\"status\") == \"FAILED\":\n        raise Exception(\"Knowledge Base creation failed\")\n    time.sleep(2)\n\nprint(kb_id)\n```\n\n**Node.js**\n```javascript\nconst accountSid = process.env.TWILIO_ACCOUNT_SID;\nconst authToken = process.env.TWILIO_AUTH_TOKEN;\nconst authHeader = \"Basic \" + btoa(`${accountSid}:${authToken}`);\n\nconst res = await fetch(\"https://memory.twilio.com/v1/ControlPlane/KnowledgeBases\", {\n    method: \"POST\",\n    headers: {\n        \"Authorization\": authHeader,\n        \"Content-Type\": \"application/json\",\n    },\n    body: JSON.stringify({\n        displayName: \"product-docs\",\n        description: \"Product documentation for customer support agents\",\n    }),\n});\n\nconst operationUrl = res.headers.get(\"Location\");\n\nlet kbId;\nwhile (true) {\n    const kb = await fetch(operationUrl, {\n        headers: { \"Authorization\": authHeader },\n    }).then(r => r.json());\n    if (kb.status === \"ACTIVE\") { kbId = kb.id; break; }\n    if (kb.status === \"FAILED\") throw new Error(\"Knowledge Base creation failed\");\n    await new Promise(r => setTimeout(r, 2000));\n}\n```\n\n### Step 2 — Add a Knowledge Source\n\nThree source types: **Web** (crawl a URL), **File** (upload PDF/CSV/Markdown/text), **Text** (inline raw text).\n\n#### Web source\n\n```python\nknowledge = requests.post(\n    f\"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge\",\n    auth=(account_sid, auth_token),\n    json={\n        \"name\": \"Product Documentation\",\n        \"description\": \"Public product docs\",\n        \"source\": {\n            \"type\": \"Web\",\n            \"url\": \"https://docs.example.com\",\n            \"crawlDepth\": 3,           # 1–10, default 2\n            \"crawlPeriod\": \"WEEKLY\"    # WEEKLY | BIWEEKLY | MONTHLY | NEVER\n        }\n    }\n).json()\n\nknowledge_id = knowledge[\"id\"]\n```\n\n#### File source (PDF, CSV, Markdown, TSV, plain text — max 16MB)\n\n```python\n# Step 1: Create the source — returns a presigned upload URL\nknowledge = requests.post(\n    f\"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge\",\n    auth=(account_sid, auth_token),\n    json={\n        \"name\": \"Company Handbook\",\n        \"source\": {\n            \"type\": \"File\",\n            \"fileName\": \"handbook.pdf\",\n            \"fileSize\": 2048576,\n            \"mimeType\": \"application/pdf\"\n        }\n    }\n).json()\n\nknowledge_id = knowledge[\"id\"]\nupload_url = knowledge[\"source\"][\"importUrl\"]   # presigned S3 URL\n\n# Step 2: PUT file to presigned URL — no auth header, URL is already signed\nwith open(\"handbook.pdf\", \"rb\") as f:\n    requests.put(upload_url, data=f, headers={\"Content-Type\": \"application/pdf\"})\n```\n\n#### Text source (inline content, max 185,000 chars)\n\n```python\nknowledge = requests.post(\n    f\"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge\",\n    auth=(account_sid, auth_token),\n    json={\n        \"name\": \"Refund Policy\",\n        \"source\": {\n            \"type\": \"Text\",\n            \"content\": \"Our refund policy: customers may return items within 30 days...\"\n        }\n    }\n).json()\n```\n\n### Step 3 — Wait for Processing\n\nKnowledge sources are processed asynchronously. Poll until `status` is `COMPLETED`.\n\n```python\ndef wait_for_knowledge(kb_id, knowledge_id):\n    while True:\n        k = requests.get(\n            f\"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge/{knowledge_id}\",\n            auth=(account_sid, auth_token)\n        ).json()\n        if k[\"status\"] == \"COMPLETED\":\n            return k\n        if k[\"status\"] == \"FAILED\":\n            raise Exception(f\"Knowledge processing failed: {k}\")\n        time.sleep(3)\n\nwait_for_knowledge(kb_id, knowledge_id)\n```\n\nStatuses: `SCHEDULED` → `QUEUED` → `PROCESSING` → `COMPLETED` / `FAILED`\n\n### Step 4 — Search and Inject into LLM\n\n**Python**\n```python\nresults = requests.post(\n    f\"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Search\",\n    auth=(account_sid, auth_token),\n    json={\n        \"query\": \"How do I reset my password?\",\n        \"top\": 5,                              # max 20\n        \"knowledgeIds\": [knowledge_id]         # optional — search specific sources\n    }\n).json()\n\nchunks = \"\\n\\n\".join(c[\"content\"] for c in results.get(\"chunks\", []))\n\nsystem_prompt = f\"\"\"You are a helpful support agent.\n\nRelevant knowledge:\n{chunks}\n\nAnswer the customer's question using only the above content.\"\"\"\n```\n\n**Node.js**\n```javascript\nconst results = await fetch(\n    `https://knowledge.twilio.com/v1/KnowledgeBases/${kbId}/Search`,\n    {\n        method: \"POST\",\n        headers: {\n            \"Authorization\": authHeader,\n            \"Content-Type\": \"application/json\",\n        },\n        body: JSON.stringify({\n            query: userMessage,\n            top: 5,\n            knowledgeIds: [knowledgeId],\n        }),\n    }\n).then(r => r.json());\n\nconst chunks = results.chunks.map(c => c.content).join(\"\\n\\n\");\nconst systemPrompt = `You are a helpful support agent.\\n\\nRelevant knowledge:\\n${chunks}`;\n```\n\n---\n\n## Key Patterns\n\n### Combine Enterprise Knowledge with Conversation Memory Recall\n\nFor the best agent responses, combine both: Enterprise Knowledge for company content, Recall for individual customer history.\n\n**Python**\n```python\n# Run both in parallel\nrecall_res = requests.post(\n    f\"https://memory.twilio.com/v1/Services/{MEMORY_STORE_SID}/Profiles/{profile_id}/Recall\",\n    auth=(account_sid, auth_token),\n    json={\"query\": user_query, \"observationsLimit\": 5}\n)\nsearch_res = requests.post(\n    f\"https://knowledge.twilio.com/v1/KnowledgeBases/{KB_ID}/Search\",\n    auth=(account_sid, auth_token),\n    json={\"query\": user_query, \"top\": 3}\n)\n\ncustomer_history = \"\\n\".join(o[\"content\"] for o in recall_res.json().get(\"observations\", []))\nknowledge_chunks = \"\\n\\n\".join(c[\"content\"] for c in search_res.json().get(\"chunks\", []))\n\nsystem_prompt = f\"\"\"Customer history:\n{customer_history}\n\nRelevant documentation:\n{knowledge_chunks}\"\"\"\n```\n\n### Refresh Stale Web Sources\n\nRe-crawl a web source without changing its config:\n\n```python\nrequests.patch(\n    f\"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge/{knowledge_id}?refresh=true\",\n    auth=(account_sid, auth_token),\n    json={}\n)\n# Returns 202 — source re-queued for processing\n```\n\n### Filter Search to Specific Sources\n\nWhen your knowledge base has multiple sources (scripts, FAQs, policies), target search to the relevant one:\n\n```python\nresults = requests.post(\n    f\"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Search\",\n    auth=(account_sid, auth_token),\n    json={\n        \"query\": \"cancellation policy\",\n        \"top\": 5,\n        \"knowledgeIds\": [policy_knowledge_id]\n    }\n).json()\n```\n\nOmit `knowledgeIds` to search across all sources in the knowledge base.\n\n### Inspect Processed Chunks\n\nTo audit what got indexed from a source:\n\n```python\nchunks = requests.get(\n    f\"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge/{knowledge_id}/Chunks\",\n    auth=(account_sid, auth_token),\n    params={\"pageSize\": 50}\n).json()\n\nfor chunk in chunks[\"chunks\"]:\n    print(chunk[\"content\"][:100])\n```\n\n---\n\n## CANNOT\n\n- **Cannot add sources before Knowledge Base is active** — Creation is async (returns 202). Poll `Location` header until `status: ACTIVE`.\n- **Cannot use one host for all operations** — Management is on `memory.twilio.com`; sources and search are on `knowledge.twilio.com`. Wrong host returns 404.\n- **Cannot include auth header when uploading to presigned URL** — `importUrl` is already signed. Adding your auth header will fail.\n- **Cannot use expired presigned URLs** — `uploadExpiration` is typically 1 hour. Upload promptly.\n- **Cannot search before processing completes** — Web crawl and file indexing are async (seconds to minutes). Poll status first.\n- **Cannot use high crawl depth without performance impact** — `crawlDepth` 1–10, default 2. Higher depths dramatically increase processing time.\n- **Cannot exceed 16MB per file upload** — Hard limit\n- **Cannot exceed 185,000 characters per text source** — Hard limit\n- **Cannot retrieve more than 20 search results per query** — `top-K` max is 20\n- **Cannot use spaces or underscores in `displayName`** — Alphanumeric and hyphens only (`^[a-zA-Z0-9-]+$`)\n- **Cannot use Knowledge for customer-specific context** — Knowledge is shared across all customers. Use `twilio-customer-memory` for per-customer context.\n- **Cannot retry FAILED sources** — Delete and recreate. No retry endpoint. Check chunk count after `COMPLETED` to verify extraction.\n\n---\n\n## Next Steps\n\n- **Per-customer context:** `twilio-customer-memory` — combine with Enterprise Knowledge for full agent context (company knowledge + individual customer history)\n- **Conversation Intelligence operators with enterprise context:** `twilio-conversation-intelligence` — feed Enterprise Knowledge chunks into Conversation Intelligence operators to give them business context. Examples:\n  - **Script Adherence:** index your approved call scripts as a knowledge source; the operator can evaluate agent compliance against the retrieved script for the current conversation type\n  - **Custom upsell classifier:** index product offers, pricing tiers, or eligibility rules; a custom classification operator can use retrieved offer details to detect upsell opportunities mid-conversation\n  - **Next Best Response:** retrieved policy or FAQ chunks injected alongside the operator prompt improve suggestion quality\n- **Wire into a voice AI agent:** `twilio-voice-conversation-relay`\n- **TAC SDK integration:** `twilio-agent-connect`\n- **Debug integration issues:** `twilio-debugging-observability`\n"
}