feat: add custom parameters support for tool definitions

Co-Authored-By: traci@launchdarkly.com <traci@launchdarkly.com>

Author: devin-ai-integration[bot]

packages/sdk/server-ai/src/ldai/__init__.py

@@ -28,6 +28,7 @@
     LDMessage,
     ModelConfig,
     ProviderConfig,
+    ToolDefinition,
 )
 from ldai.providers import (
     AgentGraphResult,
@@ -68,6 +69,7 @@
     'LDMessage',
     'ModelConfig',
     'ProviderConfig',
+    'ToolDefinition',
     'log',
     # Deprecated exports
     'AIConfig',

packages/sdk/server-ai/src/ldai/client.py

@@ -25,6 +25,7 @@
     LDMessage,
     ModelConfig,
     ProviderConfig,
+    ToolDefinition,
 )
 from ldai.providers import ToolRegistry
 from ldai.providers.runner_factory import RunnerFactory
@@ -68,7 +69,7 @@ def _completion_config(
         default: AICompletionConfigDefault,
         variables: Optional[Dict[str, Any]] = None,
     ) -> AICompletionConfig:
-        model, provider, messages, instructions, tracker, enabled, judge_configuration, _ = self.__evaluate(
+        model, provider, messages, instructions, tracker, enabled, judge_configuration, _, tools = self.__evaluate(
             key, context, default.to_dict(), variables
         )
 
@@ -80,6 +81,7 @@ def _completion_config(
             provider=provider,
             tracker=tracker,
             judge_configuration=judge_configuration,
+            tools=tools,
         )
 
         return config
@@ -134,7 +136,9 @@ def _judge_config(
         default: AIJudgeConfigDefault,
         variables: Optional[Dict[str, Any]] = None,
     ) -> AIJudgeConfig:
-        model, provider, messages, instructions, tracker, enabled, judge_configuration, variation = self.__evaluate(
+        (model, provider, messages, instructions,
+         tracker, enabled, judge_configuration,
+         variation, tools) = self.__evaluate(
             key, context, default.to_dict(), variables
         )
 
@@ -750,7 +754,8 @@ def __evaluate(
         variables: Optional[Dict[str, Any]] = None,
     ) -> Tuple[
         Optional[ModelConfig], Optional[ProviderConfig], Optional[List[LDMessage]],
-        Optional[str], LDAIConfigTracker, bool, Optional[Any], Dict[str, Any]
+        Optional[str], LDAIConfigTracker, bool, Optional[Any], Dict[str, Any],
+        Optional[List[ToolDefinition]]
     ]:
         """
         Internal method to evaluate a configuration and extract components.
@@ -828,7 +833,23 @@ def __evaluate(
                 if judges:
                     judge_configuration = JudgeConfiguration(judges=judges)
 
-        return model, provider_config, messages, instructions, tracker, enabled, judge_configuration, variation
+        tools = None
+        model_raw = variation.get('model')
+        params_raw = model_raw.get('parameters') if isinstance(model_raw, dict) else None
+        tool_defs_raw = params_raw.get('tools') if isinstance(params_raw, dict) else None
+        if isinstance(tool_defs_raw, list):
+            tools = [
+                ToolDefinition(
+                    name=t.get('name', ''),
+                    parameters=t.get('parameters', None)
+                )
+                for t in tool_defs_raw
+                if isinstance(t, dict) and t.get('name')
+            ]
+            if not tools:
+                tools = None
+
+        return model, provider_config, messages, instructions, tracker, enabled, judge_configuration, variation, tools
 
     def __evaluate_agent(
         self,
@@ -846,7 +867,7 @@ def __evaluate_agent(
         :param variables: Variables for interpolation.
         :return: Configured AIAgentConfig instance.
         """
-        model, provider, messages, instructions, tracker, enabled, judge_configuration, _ = self.__evaluate(
+        model, provider, messages, instructions, tracker, enabled, judge_configuration, _, tools = self.__evaluate(
             key, context, default.to_dict(), variables
         )
 
@@ -861,6 +882,7 @@ def __evaluate_agent(
             instructions=final_instructions,
             tracker=tracker,
             judge_configuration=judge_configuration or default.judge_configuration,
+            tools=tools or default.tools,
         )
 
     def __interpolate_template(self, template: str, variables: Dict[str, Any]) -> str:

packages/sdk/server-ai/src/ldai/models.py

@@ -77,6 +77,52 @@ def to_dict(self) -> dict:
         }
 
 
+class ToolDefinition:
+    """
+    Definition of a tool available to an AI configuration.
+
+    Each tool has a name used to match against the tool registry, and
+    optional custom parameters that can be configured via the LaunchDarkly
+    dashboard.
+    """
+
+    def __init__(self, name: str, parameters: Optional[Dict[str, Any]] = None):
+        """
+        :param name: The name of the tool.
+        :param parameters: Optional custom parameters for the tool.
+        """
+        self._name = name
+        self._parameters = parameters
+
+    @property
+    def name(self) -> str:
+        """
+        The name of the tool.
+        """
+        return self._name
+
+    def get_parameter(self, key: str) -> Any:
+        """
+        Retrieve a custom parameter by key.
+
+        :param key: The parameter key to look up.
+        :return: The parameter value, or None if not found.
+        """
+        if self._parameters is None:
+            return None
+
+        return self._parameters.get(key)
+
+    def to_dict(self) -> dict:
+        """
+        Render the tool definition as a dictionary object.
+        """
+        result: Dict[str, Any] = {'name': self._name}
+        if self._parameters is not None:
+            result['parameters'] = self._parameters
+        return result
+
+
 class ProviderConfig:
     """
     Configuration related to the provider.
@@ -208,6 +254,7 @@ class AICompletionConfigDefault(AIConfigDefault):
     """
     messages: Optional[List[LDMessage]] = None
     judge_configuration: Optional[JudgeConfiguration] = None
+    tools: Optional[List[ToolDefinition]] = None
 
     def to_dict(self) -> dict:
         """
@@ -217,6 +264,12 @@ def to_dict(self) -> dict:
         result['messages'] = [message.to_dict() for message in self.messages] if self.messages else None
         if self.judge_configuration is not None:
             result['judgeConfiguration'] = self.judge_configuration.to_dict()
+        if self.tools is not None:
+            model = result.get('model') or {}
+            params = model.get('parameters') or {}
+            params['tools'] = [tool.to_dict() for tool in self.tools]
+            model['parameters'] = params
+            result['model'] = model
         return result
 
 
@@ -227,6 +280,7 @@ class AICompletionConfig(AIConfig):
     """
     messages: Optional[List[LDMessage]] = None
     judge_configuration: Optional[JudgeConfiguration] = None
+    tools: Optional[List[ToolDefinition]] = None
 
     def to_dict(self) -> dict:
         """
@@ -250,6 +304,7 @@ class AIAgentConfigDefault(AIConfigDefault):
     """
     instructions: Optional[str] = None
     judge_configuration: Optional[JudgeConfiguration] = None
+    tools: Optional[List[ToolDefinition]] = None
 
     def to_dict(self) -> Dict[str, Any]:
         """
@@ -260,6 +315,12 @@ def to_dict(self) -> Dict[str, Any]:
             result['instructions'] = self.instructions
         if self.judge_configuration is not None:
             result['judgeConfiguration'] = self.judge_configuration.to_dict()
+        if self.tools is not None:
+            model = result.get('model') or {}
+            params = model.get('parameters') or {}
+            params['tools'] = [tool.to_dict() for tool in self.tools]
+            model['parameters'] = params
+            result['model'] = model
         return result
 
 
@@ -270,6 +331,7 @@ class AIAgentConfig(AIConfig):
     """
     instructions: Optional[str] = None
     judge_configuration: Optional[JudgeConfiguration] = None
+    tools: Optional[List[ToolDefinition]] = None
 
     def to_dict(self) -> Dict[str, Any]:
         """

packages/sdk/server-ai/tests/test_agents.py

@@ -3,7 +3,7 @@
 from ldclient.integrations.test_data import TestData
 
 from ldai import (LDAIAgentConfig, LDAIAgentDefaults, LDAIClient, ModelConfig,
-                  ProviderConfig)
+                  ProviderConfig, ToolDefinition)
 
 
 @pytest.fixture
@@ -103,6 +103,30 @@ def td() -> TestData:
         .variation_for_all(0)
     )
 
+    # Agent with tools and custom parameters
+    td.update(
+        td.flag('agent-with-tools')
+        .variations(
+            {
+                'model': {
+                    'name': 'gpt-4',
+                    'parameters': {
+                        'temperature': 0.3,
+                        'tools': [
+                            {'name': 'get-order', 'parameters': {'includeHistory': True, 'maxItems': 5}},
+                            {'name': 'search-products', 'parameters': {'category': 'electronics'}},
+                            {'name': 'send-email'},
+                        ],
+                    },
+                },
+                'provider': {'name': 'openai'},
+                'instructions': 'You are a support agent with tools.',
+                '_ldMeta': {'enabled': True, 'variationKey': 'tools-v1', 'version': 1, 'mode': 'agent'},
+            }
+        )
+        .variation_for_all(0)
+    )
+
     return td
 
 
@@ -363,3 +387,58 @@ def test_agents_request_without_default_uses_disabled(ldai_client: LDAIClient):
 
     assert 'missing-agent' in agents
     assert agents['missing-agent'].enabled is False
+
+
+def test_agent_config_has_tools(ldai_client: LDAIClient):
+    """Test that agent configs parse tools with custom parameters from flag variations."""
+    context = Context.create('user-key')
+
+    agent = ldai_client.agent_config('agent-with-tools', context)
+
+    assert agent.enabled is True
+    assert agent.tools is not None
+    assert len(agent.tools) == 3
+
+    get_order = agent.tools[0]
+    assert get_order.name == 'get-order'
+    assert get_order.get_parameter('includeHistory') is True
+    assert get_order.get_parameter('maxItems') == 5
+
+    search = agent.tools[1]
+    assert search.name == 'search-products'
+    assert search.get_parameter('category') == 'electronics'
+
+    send_email = agent.tools[2]
+    assert send_email.name == 'send-email'
+    assert send_email.get_parameter('anything') is None
+
+
+def test_agent_config_tools_fallback_to_default(ldai_client: LDAIClient):
+    """Test that agent config falls back to default tools when flag has no tools."""
+    context = Context.create('user-key')
+    default_tools = [ToolDefinition('default-tool', parameters={'timeout': 30})]
+    default = LDAIAgentDefaults(
+        enabled=False,
+        model=ModelConfig('fallback-model'),
+        instructions='Default instructions',
+        tools=default_tools,
+    )
+
+    agent = ldai_client.agent_config('customer-support-agent', context, default)
+
+    assert agent.enabled is True
+    # customer-support-agent has no tools in the flag, so falls back to default
+    assert agent.tools is not None
+    assert len(agent.tools) == 1
+    assert agent.tools[0].name == 'default-tool'
+    assert agent.tools[0].get_parameter('timeout') == 30
+
+
+def test_agent_config_no_tools(ldai_client: LDAIClient):
+    """Test that agent tools is None when neither flag nor default has tools."""
+    context = Context.create('user-key')
+
+    agent = ldai_client.agent_config('customer-support-agent', context)
+
+    assert agent.enabled is True
+    assert agent.tools is None