Ephemeral Turns

Chat with an agent without saving the turn to memory or the session store

Wrap agent.chat() calls in agent.ephemeral() to run a one-off exchange that never reaches history, the session store, or the next request.

python
from praisonaiagents import Agent

agent = Agent(name="Vision", instructions="Describe what you see.")

with agent.ephemeral():
    print(agent.chat("Describe this image", attachments=["photo.jpg"]))

# The next turn carries neither the image nor the answer.
Diagram

📋 History before

👻 ephemeral block
turns run here

✅ History after
unchanged

Quick Start

  1. Analyse an image without bloating history
    python
    from praisonaiagents import Agent
    
    agent = Agent(name="Vision", instructions="Describe what you see.")
    
    with agent.ephemeral():
        answer = agent.chat("Describe this image", attachments=["photo.jpg"])
    
    print(answer)
  2. Ask a side question in a long session
    python
    from praisonaiagents import Agent, MemoryConfig
    
    agent = Agent(
        name="Planner",
        instructions="Help plan the project.",
        memory=MemoryConfig(history=True, session_id="project-7"),
    )
    
    agent.chat("Let's plan the launch for March.")
    
    with agent.ephemeral():
        agent.chat("Quick check — how many weeks until March?")  # never saved
    
    agent.chat("Continue the launch plan.")  # history has no trace of the side question

How It Works

Diagram
Session Store / DBAgentUserSession Store / DBAgentUserwith agent.ephemeral()chat(“side question”)AnswerSave skipped (turn is ephemeral)exit blockRemove the block’s turns from chat_history
GuaranteeDetails
Not written to the JSON session storeUser, assistant and tool messages are skipped
Not written to a database adapterSame persistence path is skipped
Not written by auto_saveAuto-save is skipped while the block is active
Not sent on the next requestchat_history is rewound when the block exits
Streamed turns don’t leakPartial streamed answers are not saved either
Safe across threads and coroutinesTracked per agent and per context; other agents and concurrent turns are unaffected

Common Patterns

  • Vision prompts — image analysis you don’t want repeated on every later request. See Multimodal.
  • Sensitive one-offs — a question containing a password, PII or a secret you don’t want stored.
  • Probes and sanity checks — test the agent mid-session without changing what it remembers.

Best Practices

Scoped to one agent

The block only affects the agent you call it on. Other agents, and other turns running concurrently on the same agent, keep saving normally.

Prefer it over clearing history by hand

Clearing chat_history yourself is racy and leaves the session store and database untouched. ephemeral() handles all of them.

Pair it with long-lived sessions

Use a session_id for conversations that should persist, and wrap only the few turns that should not.


Related