multi-turn

Multi-turn Conversations

A "turn" in CubePi is one round of: user input → model response (and maybe tools) → optional more model responses to tool results. The agent's _messages list grows across turns; this guide covers how to drive multi-turn flows correctly and how to inject input while the agent is mid-thought.

The basic pattern

Just call prompt again after the previous call returns:

await agent.prompt("Hi, my name is Sam.")
await agent.prompt("What's my name?")
# → "Your name is Sam."

History lives on agent.state.messages. CubePi appends each user message, each assistant message, and each tool result. The provider gets the full list every time, so context windows matter (see Context Management below).

In-flight steering: agent.steer()

Sometimes the user has a correction or extra context while the model is still mid-turn. Use steer():

import asyncio

async def main():
    task = asyncio.create_task(agent.prompt("Plan a 5-day trip to Kyoto."))
    await asyncio.sleep(2)
    # User changed their mind:
    agent.steer(UserMessage(content=[TextContent(text="Make it 3 days, not 5.")]))
    await task

A steering message is enqueued; the loop picks it up between turns (in practice, between a tool batch and the next model call). The agent sees it before its next response — it's not lost.

steering_mode on Agent controls drain behaviour:

• "one-at-a-time" (default) — one queued message per pickup point.
• "all" — every queued message is drained at once.

Queued follow-ups: agent.follow_up()

follow_up is for "after the current run, start a new turn with this." It's the typical pattern for a chat UI: the user types while the assistant is still responding.

agent.follow_up(UserMessage(content=[TextContent(text="And what about Osaka?")]))
# When the current prompt() finishes, the loop picks this up
# automatically and starts a new turn.

If the agent is idle when you call follow_up, you still need to trigger a run — most apps call await agent.resume() once prompt() returns, to drain the queue.