From twilio-developer-kit
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.
npx claudepluginhub twilio/ai --plugin twilio-developer-kitThis skill uses the workspace's default tool permissions.
Enterprise 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-...
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Guides building MCP servers enabling LLMs to interact with external services via tools. Covers best practices, TypeScript/Node (MCP SDK), Python (FastMCP).
Share bugs, ideas, or general feedback.
Enterprise 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.
Your content (web/PDF/text) → Knowledge Base → Indexed chunks
Agent query → Search → Ranked chunks → Inject into LLM prompt
Enterprise 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.
Auth: Basic Auth — TWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN.
twilio-account-setupTWILIO_ACCOUNT_SID and TWILIO_AUTH_TOKEN — see twilio-iam-auth-setupKnowledge Bases are containers for knowledge sources. Creation is async — returns 202, poll the Location header until status: ACTIVE.
Python
import os, requests, time
account_sid = os.environ["TWILIO_ACCOUNT_SID"]
auth_token = os.environ["TWILIO_AUTH_TOKEN"]
res = requests.post(
"https://memory.twilio.com/v1/ControlPlane/KnowledgeBases",
auth=(account_sid, auth_token),
json={
"displayName": "product-docs", # alphanumeric + hyphens only
"description": "Product documentation for customer support agents"
}
)
operation_url = res.headers["Location"]
# Poll until ready
while True:
kb = requests.get(operation_url, auth=(account_sid, auth_token)).json()
if kb.get("status") == "ACTIVE":
kb_id = kb["id"]
break
if kb.get("status") == "FAILED":
raise Exception("Knowledge Base creation failed")
time.sleep(2)
print(kb_id)
Node.js
const accountSid = process.env.TWILIO_ACCOUNT_SID;
const authToken = process.env.TWILIO_AUTH_TOKEN;
const authHeader = "Basic " + btoa(`${accountSid}:${authToken}`);
const res = await fetch("https://memory.twilio.com/v1/ControlPlane/KnowledgeBases", {
method: "POST",
headers: {
"Authorization": authHeader,
"Content-Type": "application/json",
},
body: JSON.stringify({
displayName: "product-docs",
description: "Product documentation for customer support agents",
}),
});
const operationUrl = res.headers.get("Location");
let kbId;
while (true) {
const kb = await fetch(operationUrl, {
headers: { "Authorization": authHeader },
}).then(r => r.json());
if (kb.status === "ACTIVE") { kbId = kb.id; break; }
if (kb.status === "FAILED") throw new Error("Knowledge Base creation failed");
await new Promise(r => setTimeout(r, 2000));
}
Three source types: Web (crawl a URL), File (upload PDF/CSV/Markdown/text), Text (inline raw text).
knowledge = requests.post(
f"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge",
auth=(account_sid, auth_token),
json={
"name": "Product Documentation",
"description": "Public product docs",
"source": {
"type": "Web",
"url": "https://docs.example.com",
"crawlDepth": 3, # 1–10, default 2
"crawlPeriod": "WEEKLY" # WEEKLY | BIWEEKLY | MONTHLY | NEVER
}
}
).json()
knowledge_id = knowledge["id"]
# Step 1: Create the source — returns a presigned upload URL
knowledge = requests.post(
f"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge",
auth=(account_sid, auth_token),
json={
"name": "Company Handbook",
"source": {
"type": "File",
"fileName": "handbook.pdf",
"fileSize": 2048576,
"mimeType": "application/pdf"
}
}
).json()
knowledge_id = knowledge["id"]
upload_url = knowledge["source"]["importUrl"] # presigned S3 URL
# Step 2: PUT file to presigned URL — no auth header, URL is already signed
with open("handbook.pdf", "rb") as f:
requests.put(upload_url, data=f, headers={"Content-Type": "application/pdf"})
knowledge = requests.post(
f"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge",
auth=(account_sid, auth_token),
json={
"name": "Refund Policy",
"source": {
"type": "Text",
"content": "Our refund policy: customers may return items within 30 days..."
}
}
).json()
Knowledge sources are processed asynchronously. Poll until status is COMPLETED.
def wait_for_knowledge(kb_id, knowledge_id):
while True:
k = requests.get(
f"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge/{knowledge_id}",
auth=(account_sid, auth_token)
).json()
if k["status"] == "COMPLETED":
return k
if k["status"] == "FAILED":
raise Exception(f"Knowledge processing failed: {k}")
time.sleep(3)
wait_for_knowledge(kb_id, knowledge_id)
Statuses: SCHEDULED → QUEUED → PROCESSING → COMPLETED / FAILED
Python
results = requests.post(
f"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Search",
auth=(account_sid, auth_token),
json={
"query": "How do I reset my password?",
"top": 5, # max 20
"knowledgeIds": [knowledge_id] # optional — search specific sources
}
).json()
chunks = "\n\n".join(c["content"] for c in results.get("chunks", []))
system_prompt = f"""You are a helpful support agent.
Relevant knowledge:
{chunks}
Answer the customer's question using only the above content."""
Node.js
const results = await fetch(
`https://knowledge.twilio.com/v1/KnowledgeBases/${kbId}/Search`,
{
method: "POST",
headers: {
"Authorization": authHeader,
"Content-Type": "application/json",
},
body: JSON.stringify({
query: userMessage,
top: 5,
knowledgeIds: [knowledgeId],
}),
}
).then(r => r.json());
const chunks = results.chunks.map(c => c.content).join("\n\n");
const systemPrompt = `You are a helpful support agent.\n\nRelevant knowledge:\n${chunks}`;
For the best agent responses, combine both: Enterprise Knowledge for company content, Recall for individual customer history.
Python
# Run both in parallel
recall_res = requests.post(
f"https://memory.twilio.com/v1/Services/{MEMORY_STORE_SID}/Profiles/{profile_id}/Recall",
auth=(account_sid, auth_token),
json={"query": user_query, "observationsLimit": 5}
)
search_res = requests.post(
f"https://knowledge.twilio.com/v1/KnowledgeBases/{KB_ID}/Search",
auth=(account_sid, auth_token),
json={"query": user_query, "top": 3}
)
customer_history = "\n".join(o["content"] for o in recall_res.json().get("observations", []))
knowledge_chunks = "\n\n".join(c["content"] for c in search_res.json().get("chunks", []))
system_prompt = f"""Customer history:
{customer_history}
Relevant documentation:
{knowledge_chunks}"""
Re-crawl a web source without changing its config:
requests.patch(
f"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge/{knowledge_id}?refresh=true",
auth=(account_sid, auth_token),
json={}
)
# Returns 202 — source re-queued for processing
When your knowledge base has multiple sources (scripts, FAQs, policies), target search to the relevant one:
results = requests.post(
f"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Search",
auth=(account_sid, auth_token),
json={
"query": "cancellation policy",
"top": 5,
"knowledgeIds": [policy_knowledge_id]
}
).json()
Omit knowledgeIds to search across all sources in the knowledge base.
To audit what got indexed from a source:
chunks = requests.get(
f"https://knowledge.twilio.com/v1/KnowledgeBases/{kb_id}/Knowledge/{knowledge_id}/Chunks",
auth=(account_sid, auth_token),
params={"pageSize": 50}
).json()
for chunk in chunks["chunks"]:
print(chunk["content"][:100])
Location header until status: ACTIVE.memory.twilio.com; sources and search are on knowledge.twilio.com. Wrong host returns 404.importUrl is already signed. Adding your auth header will fail.uploadExpiration is typically 1 hour. Upload promptly.crawlDepth 1–10, default 2. Higher depths dramatically increase processing time.top-K max is 20displayName — Alphanumeric and hyphens only (^[a-zA-Z0-9-]+$)twilio-customer-memory for per-customer context.COMPLETED to verify extraction.twilio-customer-memory — combine with Enterprise Knowledge for full agent context (company knowledge + individual customer history)twilio-conversation-intelligence — feed Enterprise Knowledge chunks into Conversation Intelligence operators to give them business context. Examples:
twilio-voice-conversation-relaytwilio-agent-connecttwilio-debugging-observability