Make registering views for individual agents easier

Author: tomusher

docs/modules/agents/index.md

@@ -57,7 +57,7 @@ class MyAppAppConfig(AppConfig):
 
 ## Configuring Agent URLs
 
-To make your agents accessible at automatically generated URLs, add `agent_urls()` to your `urlpatterns`:
+Agents can be made accessible at automatically generated URLs by adding `agent_urls()` to your `urlpatterns`:
 
 ```python
 from django.urls import path, include
@@ -71,6 +71,18 @@ urlpatterns = [
 
 This will generate URLs under `ai/` for all your registered agents based on their `slug` values. The `SimplePromptAgent` from the above example will be accessible at `ai/prompt/`.
 
+Alternatively, you can register views for individual agents using the `as_view` classmethod on Agent classes:
+
+````python
+
+from django.urls import path, include
+from .agents import SimplePromptAgent
+
+urlpatterns = [
+    ...
+    path("ai/simple/", SimplePromptAgent.as_view()),
+]
+
 ## Using Agents
 
 Agents can either be invoked directly:
@@ -79,7 +91,7 @@ Agents can either be invoked directly:
 from .agents import SimplePromptAgent
 
 SimplePromptAgent().execute(prompt="Foo")
-```
+````
 
 or via their URL:
 
@@ -92,3 +104,25 @@ POST https://www.example.com/ai/prompt/
     }
 }
 ```
+
+## Permissions
+
+You can control who can execute your agents using permission. See the [Permissions](./permissions) documentation for detailed information on how to secure your agents.
+
+Quick example:
+
+```python
+
+from django_ai_core.contrib.agents import Agent
+from django_ai_core.contrib.agents.permissions import IsAuthenticated
+
+@registry.register()
+class SecureAgent(Agent):
+    slug = "secure"
+    description = "Agent requiring authentication"
+    permission = IsAuthenticated()
+    parameters = []
+
+    def execute(self):
+        return "Authenticated access only!"
+```

src/django_ai_core/contrib/agents/base.py

@@ -7,6 +7,7 @@
 from django.core.exceptions import ValidationError
 
 from .permissions import BasePermission
+from .views import AgentExecutionView
 
 
 @dataclass
@@ -31,6 +32,10 @@ class Agent(ABC):
     description: str
     parameters: list[AgentParameter] | None
 
+    @classmethod
+    def as_view(cls):
+        return AgentExecutionView.as_view(agent_slug=cls.slug)
+
     @classmethod
     def _derive_parameters_from_signature(cls) -> list[AgentParameter]:
         """Derive parameters from `execute` type signature"""

src/django_ai_core/contrib/agents/urls.py

@@ -1,7 +1,6 @@
 from django.urls import path
 
 from . import registry
-from .views import AgentExecutionView
 
 
 def agent_urls() -> list:
@@ -22,12 +21,12 @@ def agent_urls() -> list:
     """
     urlpatterns = []
 
-    for agent_slug in registry.list().keys():
+    for agent in registry.list().values():
         urlpatterns.append(
             path(
-                f"{agent_slug}/",
-                AgentExecutionView.as_view(agent_slug=agent_slug),
-                name=f"agent_{agent_slug}",
+                f"{agent.slug}/",
+                agent.as_view(),
+                name=f"agent_{agent.slug}",
             )
         )
 

src/django_ai_core/contrib/agents/views.py

@@ -1,14 +1,16 @@
-from typing import Any
+from typing import Any, TYPE_CHECKING
 import json
 
 from django.http import JsonResponse
 from django.views import View
 from django.views.decorators.csrf import csrf_exempt
 from django.utils.decorators import method_decorator
 
-from . import registry, Agent
 from .permissions import AllowAny
 
+if TYPE_CHECKING:
+    from . import Agent
+
 
 class AgentExecutionException(Exception):
     pass
@@ -90,11 +92,13 @@ def post(self, request):
 
         return JsonResponse({"status": "completed", "data": result})
 
-    def _get_agent(self) -> Agent:
+    def _get_agent(self) -> "Agent":
+        from . import registry
+
         try:
             return registry.get(self.agent_slug)()
         except KeyError:
             raise AgentNotFound
 
-    def _execute_agent(self, agent: Agent, arguments: dict[str, Any]) -> Any:
+    def _execute_agent(self, agent: "Agent", arguments: dict[str, Any]) -> Any:
         return agent.execute(**arguments)