From static docs to in-product agents

docs-voice-agent/
|-- autonomy.yaml           # Deployment configuration
|-- images/
|   |-- main/
|       |-- Dockerfile      # Container definition
|       |-- main.py         # Application entry point
|       |-- index.html      # Voice interface

from autonomy import Knowledge, KnowledgeTool, Model, NaiveChunker

def create_knowledge():
  return Knowledge(
    name="autonomy_docs",
    searchable=True,
    model=Model("embed-english-v3"),   # Embedding model for semantic search
    max_results=5,                     # Return top 5 relevant chunks
    max_distance=0.4,                  # Similarity threshold
    chunker=NaiveChunker(
      max_characters=1024,             # Chunk size
      overlap=128                      # Overlap between chunks
    ),
  )

import re
import httpx
from autonomy import Knowledge

LLMS_TXT_URL = "https://autonomy.computer/docs/llms.txt"  # Change to your docs URL

async def load_documents(knowledge: Knowledge):
  async with httpx.AsyncClient() as client:
    response = await client.get(LLMS_TXT_URL)
    llms_txt = response.text

  # Parse markdown links: [Title](https://url.md)
  links = re.findall(r"\[([^\]]+)\]\((https://[^\)]+\.md)\)", llms_txt)

  count = 0
  for title, url in links:
    try:
      await knowledge.add_document(
        document_name=title,
        document_url=url,
        content_type="text/markdown",
      )
      count += 1
    except Exception:
      pass

  return count

await knowledge.add_text(
  document_name="getting-started",
  text="""
  # Getting Started
  
  Welcome to our platform. Here's how to get started...
  """
)

# Markdown
await knowledge.add_document(
  document_name="api-reference",
  document_url="https://raw.githubusercontent.com/your-org/docs/main/api.md",
  content_type="text/markdown"
)

# HTML
await knowledge.add_document(
  document_name="tutorial",
  document_url="https://your-site.com/tutorial.html",
  content_type="text/html"
)

# Customize this for your product/documentation.
# Key things to change:
# - Replace "Autonomy" with your product name
# - Replace "autonomous products" with what your product does
# - Adjust the personality and tone to match your brand
# - Update the tool name reference (search_autonomy_docs -> your tool name)

INSTRUCTIONS = """
You are a developer advocate for Autonomy.
Autonomy is a platform that developers use to ship autonomous products.

You can access a knowledge base containing the complete Autonomy docs.
ALWAYS use the search_autonomy_docs tool to find accurate information before answering.

IMPORTANT: Keep your responses concise - ideally 2-4 sentences. You are primarily
used through a voice interface, so brevity is essential. Get to the point quickly
and avoid lengthy explanations unless specifically asked for more detail.

- Ask "why" questions to build empathy.
- Early in the conversation, ask questions to learn why they are talking to you. Tailor depth accordingly: technical for engineers, general for others.

- Start short. Offer to go deeper if there's more to cover.
- Lead with the point. State the main idea in the first line. Support it with short sections that follow simple logic.
- Build momentum. Each sentence sets up the next.

- Always search the knowledge base first.
- Use the exact nouns, verbs, and adjectives that are in the docs, not synonyms.
- If you can't find it, say so. Don't make stuff up. Use it as an opportunity to build trust by asking curious questions. And suggest that they search the autonomy docs page.

- Use active voice, strong verbs, and short sentences.
- Be clear, direct, confident. Teach with calm authority.
"""

# Customize this for your product/documentation.
# Key things to change:
# - Replace "Autonomy" with your product name
# - Replace "autonomous products" with what your product does  
# - Adjust the personality to match your brand voice
# - Modify the example lead-in phrases to fit your tone

VOICE_INSTRUCTIONS = """
You are a developer advocate for Autonomy.
Autonomy is a platform that developers use to ship autonomous products.

# Critical Rules

- Before giving your full response, speak a short, casual lead-in that feels spontaneous and human.
  - Use a light reaction or framing cue that fits ordinary conversation and feels like a reaction to what they just said.
  - For example, you might say something like "Good question", "Glad you asked.", "Right, great question. So.", "Here's a clear way to view it.", "Here's the core idea,", "Let's start with the basics," or a similar phrase in that style. You may invent new variations each time.
  - Keep it brief, warm, and conversational.
  - Do not mention looking up, searching, finding, checking, getting, thinking, loading, or waiting. Keep the lead-in a few seconds long.
- After speaking the lead-in, delegate to the primary agent for the rest of the response.
- NEVER answer questions about Autonomy from your own knowledge - always delegate.

# Conversational Pattern

This two-step pattern is REQUIRED:
  User: "How do agents work?"
  You: "Good question." [speak this lead-in first, then delegate]
  [after delegation returns]
  You: [speak the answer from the primary agent]

# What You Can Handle Directly
- Greetings: "Hello", "Hi there"
- Clarifications: "Could you repeat that?"
- Farewells: "Goodbye", "Thanks"

# After Receiving Response
Read the primary agent's response verbatim. Do NOT change it in any way or add anything to it.

# Personality
- Be friendly, conversational, and human - not robotic
- Be clear, direct, confident, and encouraging
- Use active voice, strong verbs, and short sentences
"""

from autonomy import Agent, Model, KnowledgeTool, Node

async def main(node: Node):
  global knowledge_tool

  knowledge = create_knowledge()
  knowledge_tool = KnowledgeTool(knowledge=knowledge, name="search_autonomy_docs")

  await Agent.start(
    node=node,
    name="docs",
    instructions=INSTRUCTIONS,
    model=Model("claude-sonnet-4-v1", max_tokens=256),
    tools=[knowledge_tool],
    context_summary={
      "floor": 20,
      "ceiling": 30,
      "model": Model("claude-sonnet-4-v1"),
    },
    voice={
      "voice": "alloy",
      "instructions": VOICE_INSTRUCTIONS,
      "vad_threshold": 0.7,
      "vad_silence_duration_ms": 700,
    },
  )

  await load_documents(knowledge)
  asyncio.create_task(periodic_refresh())

import asyncio
from fastapi import FastAPI
from autonomy import HttpServer

REFRESH_INTERVAL_SECONDS = 1800  # 30 minutes

app = FastAPI()
knowledge_tool = None

async def refresh_knowledge():
  global knowledge_tool
  new_knowledge = create_knowledge()
  count = await load_documents(new_knowledge)
  knowledge_tool.knowledge = new_knowledge
  return count

async def periodic_refresh():
  while True:
    await asyncio.sleep(REFRESH_INTERVAL_SECONDS)
    try:
      await refresh_knowledge()
    except Exception:
      pass

@app.post("/refresh")
async def refresh_endpoint():
  count = await refresh_knowledge()
  return {"status": "ok", "documents_loaded": count}

name: docs
pods:
  - name: main-pod
    public: true
    containers:
      - name: main
        image: main

FROM ghcr.io/build-trust/autonomy-python
COPY . .
ENTRYPOINT ["python", "main.py"]

const protocol = window.location.protocol === "https:" ? "wss:" : "ws:";
const wsUrl = `${protocol}//${window.location.host}/agents/docs/voice?scope=${visitorId}&conversation=${id()}`;

ws = new WebSocket(wsUrl);

ws.onmessage = async (event) => {
  const data = JSON.parse(event.data);
  await handleServerMessage(data);
};

mediaStream = await navigator.mediaDevices.getUserMedia({
  audio: {
    channelCount: 1,
    sampleRate: 24000,
    echoCancellation: true,
    noiseSuppression: true,
    autoGainControl: true,
  },
});

// AudioWorklet processes audio in real-time
workletNode.port.onmessage = (e) => {
  const { pcm16 } = e.data;
  const audioBase64 = btoa(String.fromCharCode(...new Uint8Array(pcm16)));
  ws.send(JSON.stringify({ type: "audio", audio: audioBase64 }));
};

async function playAudioChunk(base64Audio) {
  const audioBytes = Uint8Array.from(atob(base64Audio), (c) => c.charCodeAt(0));
  const pcm16 = new Int16Array(audioBytes.buffer);
  const float32 = new Float32Array(pcm16.length);

  for (let i = 0; i < pcm16.length; i++) {
    float32[i] = pcm16[i] / 32768.0;
  }

  const audioBuffer = playbackAudioContext.createBuffer(1, float32.length, 24000);
  audioBuffer.getChannelData(0).set(float32);

  const source = playbackAudioContext.createBufferSource();
  source.buffer = audioBuffer;
  source.connect(playbackAudioContext.destination);
  source.start(nextPlayTime);
  nextPlayTime += audioBuffer.duration;
}

async function handleServerMessage(data) {
  switch (data.type) {
    case "audio":
      await playAudioChunk(data.audio);
      break;
    case "transcript":
      addTranscript(data.role, data.text);
      break;
    case "speech_started":
      clearAudioQueue(); // Stop playback when user speaks
      break;
    case "response_complete":
      // Ready for next input
      break;
  }
}

function addTranscript(role, text) {
  const item = document.createElement("div");
  item.className = "transcript-item " + role;
  item.innerHTML = `
    <div class="role">${role === "user" ? "You" : "Assistant"}</div>
    <div>${text}</div>
  `;
  transcriptContainer.appendChild(item);
  transcriptContainer.scrollTop = transcriptContainer.scrollHeight;
}

// Fetch with streaming enabled
const response = await fetch(`/agents/docs?stream=true`, {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ 
    message: userMessage, 
    scope: visitorId,        // Multi-tenant: isolate per user
    conversation: chatId     // Isolate per conversation
  }),
});

// Read the stream
const reader = response.body.getReader();
const decoder = new TextDecoder();
let pendingText = "";
let displayedText = "";

// Typewriter loop - display text gradually for better UX
const typewriterLoop = async () => {
  while (!streamDone || pendingText.length > 0) {
    if (pendingText.length > 0) {
      const chars = pendingText.slice(0, 3); // Display 3 chars at a time
      pendingText = pendingText.slice(3);
      displayedText += chars;
      updateMessageDisplay(displayedText);
      await new Promise(r => setTimeout(r, 2)); // Small delay between chunks
    }
  }
};

// Read stream and queue text for typewriter
while (true) {
  const { done, value } = await reader.read();
  if (done) break;
  
  const chunk = decoder.decode(value, { stream: true });
  // Parse SSE data and add to pendingText
  // The typewriter loop displays it gradually
}

from autonomy import Agent, FilesystemTools, Model, Node
import httpx

async def main(node: Node):
  # Download docs to the filesystem
  await download_docs_to_filesystem()
  
  await Agent.start(
    node=node,
    name="docs",
    instructions="""
    You are a documentation assistant.
    
    Use these tools to find and read documentation:
    - find_files: Find docs by pattern (e.g., "**/*.md" for all markdown files)
    - list_directory: Explore the documentation structure
    - search_in_files: Search for specific terms across all docs
    - read_file: Read the content of specific files
    
    Keep responses concise for voice interaction.
    """,
    model=Model("claude-sonnet-4-v1", max_tokens=256),
    tools=[FilesystemTools(visibility="agent")],
    voice={
      "voice": "alloy",
      "instructions": VOICE_INSTRUCTIONS,
      "vad_threshold": 0.7,
      "vad_silence_duration_ms": 700,
    },
  )

Node.start(main)