Quick Start
Swap an agent model mid-conversation
Update the target model at any time — the next invocation automatically picks up the change because
agent.chat() reads the live llm value.Inspect the runtime cache
Use
get_runtime_cache and clear_runtime_cache to debug or force a fresh resolution.How It Works
The subsystem reads the agent’s currentllm (or model) attribute at invocation time, not at construction time.
Handoffs always execute via
agent.chat() / agent.achat() directly — they do not call into this subsystem. Runtime resolution is used for agent-level model configuration and caching, not for handoff execution.Configuration Options
SessionContext
Passed to resolve_runtime to scope caching and track depth.
| Field | Type | Default | Description |
|---|---|---|---|
session_id | str | — | Required. Used as the first segment of the cache key |
timestamp | float | time.time() if <= 0 | Session start time |
parent_agent_id | Optional[str] | None | Name of the agent that triggered resolution |
handoff_depth | int | 0 | Current nesting depth |
Cache constants
| Constant | Value | Meaning |
|---|---|---|
_cache_ttl_seconds | 300 | Each cached runtime lives for 5 minutes |
_cleanup_interval | 600 | Background cleanup daemon runs every 10 minutes |
"{session_id}:{agent_id}:{model_ref}" — caches are session-isolated so different conversations never share runtimes.
Common Patterns
Mid-conversation model swap
Force cache refresh
Introspect resolved runtimes
Best Practices
Change llm before starting a new turn
Change llm before starting a new turn
Model re-resolution happens at each invocation boundary. Changing
agent.llm is effective immediately for the next call — no restart needed.Use clear_runtime_cache after credential rotation
Use clear_runtime_cache after credential rotation
The 5-minute TTL means old runtimes may linger after you rotate API keys. Call
clear_runtime_cache() to evict all entries and force fresh connections.Implement supports_model narrowly in custom resolvers
Implement supports_model narrowly in custom resolvers
Return
False from supports_model for models you do not handle. The built-in DefaultRuntimeResolver acts as the final fallback, so returning False simply delegates back to it.Handoffs execute via agent.chat() — not this subsystem
Handoffs execute via agent.chat() — not this subsystem
If you need to change how a handoff target executes, configure the target agent itself (instructions, tools, llm). The target agent’s full
chat() pipeline runs on every handoff — this subsystem is not in that path.Public API
All names are importable frompraisonaiagents.runtime:
resolve_runtime
RuntimeProtocol / AgentRuntimeProtocol
Protocols that custom runtimes must satisfy. Only relevant when building a custom resolver.
Related
Agent Handoffs
Agent-to-agent delegation — handoffs always use agent.chat()
HandoffConfig reference
HandoffConfig reference
Secure tool boundaries during handoff
Secure tool boundaries during handoff
Filter context passed during handoff
Filter context passed during handoff

