Derive agent parameters from types

Author: tomusher

docs/modules/core.md

@@ -18,19 +18,19 @@ It uses the [`any-llm`](https://mozilla-ai.github.io/any-llm/) package to provid
 
 To use the `LLMService`:
 
-````python
+```python
 
 from django_ai_core.llm import LLMService
 
 service = LLMService.create(
     provider="openai",
     model="gpt-4o"
-)```
+)
+```
 
 You can also alternatively instantiate `LLMService` with your own client instance:
 
-````
-
+```python
 from any_llm import AnyLLM
 
 client = AnyLLM.create(
@@ -39,14 +39,22 @@ model="gpt-4o"
 )
 
 service = LLMService(client=client)
-
 ```
 
 # Completions
-response = service.completion("What is the airspeed velocity of an unladen swallow?")
+
+```python
+response = service.completion(
+    "What is the airspeed velocity of an unladen swallow?"
+)
+```
 
 # Embeddings
-response = service.embedding("What's the speed on that bird when it's not hauling stuff?")
+
+```python
+response = service.embedding(
+    "What's the speed on that bird when it's not hauling stuff?"
+)
 ```
 
 All keyword arguments are passed to the underlying `any-llm` [`completion`](https://mozilla-ai.github.io/any-llm/api/completion/) and [`embedding`](https://mozilla-ai.github.io/any-llm/api/embedding/) APIs.

src/django_ai_core/contrib/agents/base.py

@@ -1,5 +1,7 @@
+import inspect
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
+from typing import get_args, get_origin, Annotated
 
 from django.core.validators import validate_slug
 from django.core.exceptions import ValidationError
@@ -11,13 +13,39 @@ class AgentParameter:
     type: type
     description: str
 
+    def as_dict(self):
+        return {
+            "name": self.name,
+            "type": self.type.__name__,
+            "description": self.description,
+        }
+
 
 class Agent(ABC):
     """Base class for agents."""
 
     slug: str
     description: str
-    parameters: list[AgentParameter]
+    parameters: list[AgentParameter] | None
+
+    @classmethod
+    def _derive_parameters_from_signature(cls) -> list[AgentParameter]:
+        """Derive parameters from `execute` type signature"""
+        parameters = []
+        annotations = inspect.get_annotations(cls.execute)
+        for name, annotation in annotations.items():
+            if name == "return":
+                continue
+            description: str = ""
+            base_type = annotation
+            if get_origin(annotation) is Annotated:
+                base_type, *metadata = get_args(annotation)
+                if metadata and isinstance(metadata[0], str):
+                    description = metadata[0]
+            parameters.append(
+                AgentParameter(name=name, type=base_type, description=description)
+            )
+        return parameters
 
     @abstractmethod
     def execute(self, *args, **kwargs) -> str:
@@ -26,6 +54,9 @@ def execute(self, *args, **kwargs) -> str:
     def __init_subclass__(cls, **kwargs):
         super().__init_subclass__(**kwargs)
 
+        if "parameters" not in cls.__dict__:
+            cls.parameters = cls._derive_parameters_from_signature()
+
         if hasattr(cls, "slug"):
             try:
                 validate_slug(cls.slug)
@@ -39,11 +70,11 @@ class AgentRegistry:
     def __init__(self):
         self._agents: dict[str, type[Agent]] = {}
 
-    def register(self, slug: str | None = None):
+    def register(self):
         """Decorator to register an agent."""
 
         def decorator(cls: type[Agent]) -> type[Agent]:
-            agent_slug = slug or getattr(cls, "slug", cls.__name__.lower())
+            agent_slug = getattr(cls, "slug")
             self._agents[agent_slug] = cls
             return cls
 

src/django_ai_core/contrib/agents/views.py

@@ -1,4 +1,4 @@
-from typing import Any, Type
+from typing import Any
 import json
 
 from django.http import JsonResponse
@@ -9,10 +9,38 @@
 from . import registry, Agent
 
 
+class AgentExecutionException(Exception):
+    pass
+
+
+class AgentNotFound(AgentExecutionException):
+    code = "agent_not_found"
+
+
 @method_decorator(csrf_exempt, name="dispatch")
 class AgentExecutionView(View):
     agent_slug: str = ""
 
+    def get(self, request):
+        try:
+            agent = self._get_agent()
+        except AgentNotFound as e:
+            return JsonResponse(
+                {
+                    "error": f"Agent not found: {self.agent_slug}",
+                    "code": e.code,
+                },
+                status=404,
+            )
+
+        return JsonResponse(
+            {
+                "slug": agent.slug,
+                "description": agent.description,
+                "parameters": [param.as_dict() for param in agent.parameters or []],
+            }
+        )
+
     def post(self, request):
         """
         Execute the agent with provided input data.
@@ -35,12 +63,12 @@ def post(self, request):
             )
 
         try:
-            agent = registry.get(self.agent_slug)
-        except KeyError:
+            agent = self._get_agent()
+        except AgentNotFound as e:
             return JsonResponse(
                 {
                     "error": f"Agent not found: {self.agent_slug}",
-                    "code": "agent_not_found",
+                    "code": e.code,
                 },
                 status=404,
             )
@@ -49,7 +77,11 @@ def post(self, request):
 
         return JsonResponse({"status": "completed", "data": result})
 
-    def _execute_agent(self, agent_cls: Type[Agent], arguments: dict[str, Any]) -> Any:
-        agent = agent_cls()
+    def _get_agent(self) -> Agent:
+        try:
+            return registry.get(self.agent_slug)()
+        except KeyError:
+            raise AgentNotFound
 
+    def _execute_agent(self, agent: Agent, arguments: dict[str, Any]) -> Any:
         return agent.execute(**arguments)

tests/testapp/agents.py

@@ -1,17 +1,20 @@
-from django_ai_core.contrib.agents import Agent, AgentParameter, registry
+from django_ai_core.contrib.agents import Agent, registry
+from typing import Annotated
 
 
 @registry.register()
 class BasicAgent(Agent):
-    name = "basic"
+    slug = "basic"
     description = "Basic agent that just takes a prompt and returns a response."
-    parameters = [
-        AgentParameter(
-            name="prompt",
-            type=str,
-            description="The prompt to use for the agent",
-        ),
-    ]
 
-    def execute(self, *, prompt: str):
+    def execute(self, *, prompt: Annotated[str, "The prompt to use for the agent"]):
         return prompt
+
+
+@registry.register()
+class StubAgent(Agent):
+    slug = "stub"
+    description = "Basic agent that just takes a prompt and returns a response."
+
+    def execute(self):
+        return ""

tests/unit/contrib/agents/test_agent_base.py

@@ -1,4 +1,5 @@
 import pytest
+from typing import Annotated
 
 from django_ai_core.contrib.agents.base import Agent, AgentParameter
 
@@ -29,6 +30,7 @@ def test_agent_initialization():
 
     assert agent.slug == "test-agent"
     assert agent.description == "Test agent for testing"
+    assert agent.parameters
     assert len(agent.parameters) == 2
 
     # Check parameter definitions
@@ -86,3 +88,115 @@ def test_agent_parameter_dataclass():
     assert param.name == "test"
     assert param.type is bool
     assert param.description == "A test parameter"
+
+
+def test_agent_parameter_as_dict():
+    """Test AgentParameter.as_dict() method."""
+    param = AgentParameter(
+        name="test_param",
+        type=str,
+        description="A test parameter",
+    )
+
+    result = param.as_dict()
+
+    assert result == {
+        "name": "test_param",
+        "type": "str",
+        "description": "A test parameter",
+    }
+
+
+def test_derive_parameters_from_signature():
+    """Test _derive_parameters_from_signature method."""
+
+    class TestAgentWithAnnotations(Agent):
+        slug = "test-annotated"
+        description = "Test agent with type annotations"
+
+        def execute(
+            self,
+            *,
+            name: Annotated[str, "The name parameter"],
+            count: Annotated[int, "The count parameter"],
+        ):
+            return f"Hello {name}, count is {count}"
+
+    agent = TestAgentWithAnnotations()
+
+    assert agent.parameters
+    assert len(agent.parameters) == 2
+
+    name_param = agent.parameters[0]
+    assert name_param.name == "name"
+    assert name_param.type is str
+    assert name_param.description == "The name parameter"
+
+    count_param = agent.parameters[1]
+    assert count_param.name == "count"
+    assert count_param.type is int
+    assert count_param.description == "The count parameter"
+
+
+def test_derive_parameters_without_descriptions():
+    """Test parameter derivation without Annotated descriptions."""
+
+    class TestAgentAnnotatedWithoutDescriptions(Agent):
+        slug = "test-no-desc"
+        description = "Test agent without descriptions"
+
+        def execute(self, *, value: str, flag: bool):
+            return "result"
+
+    agent = TestAgentAnnotatedWithoutDescriptions()
+
+    assert agent.parameters
+    assert len(agent.parameters) == 2
+
+    value_param = agent.parameters[0]
+    assert value_param.name == "value"
+    assert value_param.type is str
+    assert value_param.description == ""
+
+    flag_param = agent.parameters[1]
+    assert flag_param.name == "flag"
+    assert flag_param.type is bool
+    assert flag_param.description == ""
+
+
+def test_explicit_parameters_override_derived():
+    """Test that explicit parameters take precedence over derived ones."""
+
+    class AgentWithExplicitParams(Agent):
+        slug = "test-explicit"
+        description = "Test agent with explicit parameters"
+        parameters = [
+            AgentParameter(
+                name="custom",
+                type=str,
+                description="Custom parameter",
+            ),
+        ]
+
+        def execute(self, *, name: Annotated[str, "Should be ignored"]):
+            return "result"
+
+    agent = AgentWithExplicitParams()
+
+    assert agent.parameters
+    assert len(agent.parameters) == 1
+    assert agent.parameters[0].name == "custom"
+    assert agent.parameters[0].description == "Custom parameter"
+
+
+def test_agent_without_parameter_schema():
+    class AgentWithNoParams(Agent):
+        slug = "test-explicit"
+        description = "Test agent with explicit parameters"
+
+        def execute(self, *, name):
+            return "result"
+
+    agent = AgentWithNoParams()
+
+    assert not agent.parameters