Context Management

Overview

Context management controls what your LLM sees on each turn of a live conversation. In Piopiy, this context is managed automatically inside the VoiceAgent pipeline so your agent can stay coherent across back-and-forth speech.

How Context Works in Piopiy

For each session:

1. VoiceAgent(instructions=...) creates the initial system context.
2. Incoming speech is transcribed by STT and added as user turns.
3. LLM responses are added as assistant turns.
4. The context remains isolated to that single call/session.

This gives you per-session conversation memory without manually stitching message arrays in your app code.

Seed Context at Session Start

The most reliable pattern is to inject business context (plan, language, account state) into instructions when creating the VoiceAgent.

import os
from piopiy.agent import Agent
from piopiy.voice_agent import VoiceAgent

async def on_new_session(agent_id, call_id, from_number, to_number, metadata=None):
    metadata = metadata or {}
    customer_tier = metadata.get("tier", "standard")
    preferred_language = metadata.get("language", "en-US")

    instructions = (
        "You are a phone support assistant. "
        "Speak clearly and keep answers concise. "
        f"Customer tier: {customer_tier}. "
        f"Preferred language: {preferred_language}."
    )

    voice_agent = VoiceAgent(
        instructions=instructions,
        greeting="Hello, how can I help you today?",
    )

    # initialize stt / llm / tts
    await voice_agent.Action(stt=stt, llm=llm, tts=tts, allow_interruptions=True)
    await voice_agent.start()

Keep Context Clean and Useful

• Keep system instructions explicit and short.
• Put stable policy in instructions; put runtime facts in metadata.
• Return concise, structured tool outputs (avoid very large blobs).
• Avoid repeating the same long text every turn.
• Confirm critical details (IDs, dates, amounts) aloud before final actions.

Context and Turn-Taking

For natural conversations, context quality depends on turn quality:

• Enable interruptions with allow_interruptions=True.
• Use VAD to detect user speech quickly.
• Keep TTS responses concise so users can correct or interrupt early.

await voice_agent.Action(
    stt=stt,
    llm=llm,
    tts=tts,
    vad={
        "confidence": 0.7,
        "start_secs": 0.2,
        "stop_secs": 0.8,
        "min_volume": 0.6,
    },
    allow_interruptions=True,
)

Long-Term Memory Pattern

Piopiy context is session-scoped by default. For cross-session memory:

1. Load a short customer summary from your database at session start.
2. Inject that summary into instructions.
3. Update your stored summary from tool/business events after the call.

This keeps runtime prompts compact while still giving continuity across calls.

What's Next

• Large Language Models: Choose and configure your LLM provider stack.
• Pipeline: Understand how STT -> context -> LLM -> TTS is orchestrated.
• Telephony: Apply context strategy in real call-routing deployments.