Universal Agent Factory — create, run, and orchestrate AI agents across frameworks

Failure modes

Symptom	Cause	Fix	Severity
`RuntimeWarning: coroutine 'BaseAgent.invoke' was never awaited`	`invoke` / `run` called without `await`	They are coroutines — `await` them or use `asyncio.run`	high
Constructing a non-native factory raises / `is_available()` is `False`	The framework's optional dependency isn't installed	Install the framework extra, or use `native`; check `list_frameworks(installed_only=True)`	high
`recommend_framework` / `list_frameworks` "needs an instance" error	Called as if instance-only	They are callable on the class; call `AgentFactory.list_frameworks()`	low
`get_agent(name)` returns `None`	No agent with that name was created on this factory	Check `list_agents()`; names are per-factory	low
A tool isn't used by the agent	Tool not added / wrong schema	Build it with `create_tool(...)` and pass it via `tools=` or `add_tool(...)`	medium

The run methods are async. invoke, run, and stream are coroutines — forgetting to await is the most common mistake.
Non-native frameworks are optional. They load lazily; check is_available() / list_frameworks(installed_only=True) before selecting one.
Scope. This feature is the Factory; the release agent team and its state store live under release-prep, not here.

Confirm you are awaiting: await agent.invoke(...) / await workflow.run(...).
Confirm the framework is installed: AgentFactory.list_frameworks( installed_only=True).
For a missing agent, check list_agents().
For tool issues, confirm the tool was built with create_tool and attached.