feat: throw exception if running sync run/create methods in async context (#741)

* docs: Update README and documentation for synchronous and asynchronous method usage

* fix: Prevent calling synchronous methods in async context\

* cleanup

* unit tests

Author: njbrake

src/any_agent/frameworks/any_agent.py

@@ -129,12 +129,20 @@ def create(
         agent_config: AgentConfig,
     ) -> AnyAgent:
         """Create an agent using the given framework and config."""
-        return run_async_in_sync(
-            cls.create_async(
-                agent_framework=agent_framework,
-                agent_config=agent_config,
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            # No running event loop - this is what we want for sync execution
+            return run_async_in_sync(
+                cls.create_async(
+                    agent_framework=agent_framework,
+                    agent_config=agent_config,
+                )
             )
-        )
+
+        # If we get here, there IS a running loop
+        msg = "Cannot call 'create()' from an async context. Use 'create_async()' instead."
+        raise RuntimeError(msg)
 
     @classmethod
     async def create_async(
@@ -160,7 +168,15 @@ async def _load_tools(
 
     def run(self, prompt: str, **kwargs: Any) -> AgentTrace:
         """Run the agent with the given prompt."""
-        return run_async_in_sync(self.run_async(prompt, **kwargs))
+        try:
+            asyncio.get_running_loop()
+        except RuntimeError:
+            # No running event loop - this is what we want for sync execution
+            return run_async_in_sync(self.run_async(prompt, **kwargs))
+
+        # If we get here, there IS a running loop
+        msg = "Cannot call 'run()' from an async context. Use 'run_async()' instead."
+        raise RuntimeError(msg)
 
     async def run_async(self, prompt: str, **kwargs: Any) -> AgentTrace:
         """Run the agent asynchronously with the given prompt.

tests/unit/frameworks/test_any_agent.py

@@ -92,3 +92,27 @@ def test_model_args_streaming(
         assert mock_litellm.call_args.kwargs["temperature"] == TEST_TEMPERATURE
         assert mock_litellm.call_args.kwargs["frequency_penalty"] == TEST_PENALTY
         assert mock_litellm.call_count > 0
+
+
+@pytest.mark.asyncio
+async def test_create_sync_in_async_context() -> None:
+    with pytest.raises(
+        RuntimeError,
+        match=r"Cannot call 'create\(\)' from an async context\. Use 'create_async\(\)' instead\.",
+    ):
+        AnyAgent.create(
+            AgentFramework.TINYAGENT,
+            AgentConfig(model_id="mistral/mistral-small-latest"),
+        )
+
+
+@pytest.mark.asyncio
+async def test_run_sync_in_async_context() -> None:
+    agent = await AnyAgent.create_async(
+        AgentFramework.TINYAGENT, AgentConfig(model_id="mistral/mistral-small-latest")
+    )
+    with pytest.raises(
+        RuntimeError,
+        match=r"Cannot call 'run\(\)' from an async context\. Use 'run_async\(\)' instead\.",
+    ):
+        agent.run(TEST_QUERY)