Skip to main content
Interactive agents are designed for real-time conversations and streaming responses. They are routed through Charm’s interactive worker instead of the standard serverless execution path. There is no charm init --template interactive starter. Use any scaffold (for example python), then set runtime.lifecycle: interactive in charm.yaml as shown below.

​
Use Case

Use this lifecycle for chat-style agents that need low-latency streaming, thread history, and real-time user interaction.

​
Prerequisites

  • Charm CLI.
  • A supported interactive runtime.
  • Published version available in Charm Store for end-to-end UI testing.

​
Configuration Surface

Document these fields:
  • runtime.lifecycle: interactive
  • runtime.adapter.type
  • interface.input
  • runtime.adapter.environment_variables
Example: 
runtime:
  adapter:
    type: "custom"
    entry_point: "src.main:agent"
    environment_variables:
      models:
        - OPENAI_API_KEY
  lifecycle: "interactive"

​
How Interactive Runs Work

  1. The Store sends the user’s message to the runner.
  2. The runner authenticates the user and creates a run record.
  3. The runner forwards the request to the interactive worker.
  4. The worker streams assistant output back to the browser.
  5. Completion callbacks persist the run and messages.

​
Local and Staging Testing

  • Use the Store UI to test thread behavior.
  • Confirm the published version has runtime.lifecycle: interactive.
  • Confirm the runner has CHARM_INTERACTIVE_WORKER_URL configured in staging or production.
  • Confirm required environment variables are available to the worker.

​
Run and Publish

charm validate .
charm push

​
Limitations

Interactive agents should return quickly and stream user-facing output. Long-running background tasks are a better fit for Daemon Agent.