> ## Documentation Index
> Fetch the complete documentation index at: https://docs.charmos.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Interactive Agent Template

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:

```yaml theme={"theme":{"light":"min-light","dark":"min-dark"}}
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

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
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](/templates/daemon).