Context: Communicate with the User

The Context object (ctx) is passed to every node and serves as your primary interface for communicating with the user, reading and writing state, and accessing extraction helpers. It bridges the gap between your node logic and the underlying STT/LLM/TTS pipeline.

ctx.ask(instruction) : LLM-Generated Response

Use ctx.ask() when you want the LLM to rephrase your instruction into natural, conversational language. You provide the intent as a prompt, and the LLM generates a human-friendly response that is spoken to the user via TTS.

async def approve(state, ctx):
    await ctx.ask(
        f"Congratulate {state.name} on their loan approval for Rs {state.loan_amount:,}."
    )
    return END

ctx.say(message) : Verbatim Speech

Use ctx.say() when you need exact, deterministic output - the message is sent directly to TTS without any LLM processing. This is ideal for legal disclaimers, phone numbers, URLs, or any text that must be spoken word-for-word.

async def status_check(state, ctx):
    await ctx.say("To check your status, visit loans.example.com or call 1800-XXX-XXXX.")
    return END

State Access

The ctx object also provides helper methods to read, write, and manage state values programmatically. These are an alternative to direct attribute access on the state object.

ctx.get_state("name")                                    # read
ctx.set_state("name", "Alice")                           # write
ctx.update_states({"name": "Alice", "income": 500000})   # bulk update
ctx.clear_state("loan_amount")                           # reset to None
ctx.states                                                # dict of all values

ctx.extractor

The extractor helper provides methods for structured data collection and intent classification using the LLM. See Extractor for the full guide.

ctx.human_input

Contains the payload passed via graph.resume_with_human_input(payload) when a paused graph is resumed. This is only available inside a node that previously returned HumanInLoop. See Human-in-the-Loop for the full guide.

async def manual_review(state, ctx):
    if ctx.human_input:
        return Route("approve" if ctx.human_input["decision"] == "approved" else "reject")
    return HumanInLoop(reason="Needs manager approval")