ibm-watsonx-orchestrate 1.6.3__py3-none-any.whl → 1.6.4__py3-none-any.whl

ibm_watsonx_orchestrate/agent_builder/tools/python_tool.py

@@ -5,9 +5,6 @@ import os
 from typing import Any, Callable, Dict, List, get_type_hints
 import logging
 
-import docstring_parser
-from langchain_core.tools.base import create_schema_from_function
-from langchain_core.utils.json_schema import dereference_refs
 from pydantic import TypeAdapter, BaseModel
 
 from ibm_watsonx_orchestrate.utils.utils import yaml_safe_load
@@ -15,6 +12,7 @@ from ibm_watsonx_orchestrate.agent_builder.connections import ExpectedCredential
 from .base_tool import BaseTool
 from .types import PythonToolKind, ToolSpec, ToolPermission, ToolRequestBody, ToolResponseBody, JsonSchemaObject, ToolBinding, \
     PythonToolBinding
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 
 _all_tools = []
 logger = logging.getLogger(__name__)
@@ -25,15 +23,136 @@ JOIN_TOOL_PARAMS = {
     'messages': List[Dict[str, Any]],
 }
 
+def _parse_expected_credentials(expected_credentials: ExpectedCredentials | dict):
+    parsed_expected_credentials = []
+    if expected_credentials:
+        for credential in expected_credentials:
+            if isinstance(credential, ExpectedCredentials):
+                parsed_expected_credentials.append(credential)
+            else:
+                parsed_expected_credentials.append(ExpectedCredentials.model_validate(credential))
+    
+    return parsed_expected_credentials
+
 class PythonTool(BaseTool):
-    def __init__(self, fn, spec: ToolSpec, expected_credentials: List[ExpectedCredentials]=None):
-        BaseTool.__init__(self, spec=spec)
+    def __init__(self,
+                fn,
+                name: str = None,
+                description: str = None,
+                input_schema: ToolRequestBody = None,
+                output_schema: ToolResponseBody = None,
+                permission: ToolPermission = ToolPermission.READ_ONLY,
+                expected_credentials: List[ExpectedCredentials] = None,
+                display_name: str = None,
+                kind: PythonToolKind = PythonToolKind.TOOL,
+                spec=None
+                ):
         self.fn = fn
-        self.expected_credentials=expected_credentials
+        self.name = name
+        self.description = description
+        self.input_schema = input_schema
+        self.output_schema = output_schema
+        self.permission = permission
+        self.display_name = display_name
+        self.kind = kind
+        self.expected_credentials=_parse_expected_credentials(expected_credentials)
+        self._spec = None
+        if spec:
+            self._spec = spec
 
     def __call__(self, *args, **kwargs):
         return self.fn(*args, **kwargs)
+    
+    @property
+    def __tool_spec__(self):
+        if self._spec:
+            return self._spec
+        
+        import docstring_parser
+        from langchain_core.tools.base import create_schema_from_function
+        from langchain_core.utils.json_schema import dereference_refs
+
+        if self.fn.__doc__ is not None:
+            doc = docstring_parser.parse(self.fn.__doc__)
+        else:
+            doc = None
+
+        _desc = self.description
+        if self.description is None and doc is not None:
+            _desc = doc.description
+
+        
+        spec = ToolSpec(
+            name=self.name or self.fn.__name__,
+            display_name=self.display_name,
+            description=_desc,
+            permission=self.permission
+        )
+
+        spec.binding = ToolBinding(python=PythonToolBinding(function=''))
+
+        linux_friendly_os_cwd = os.getcwd().replace("\\", "/")
+        function_binding = (inspect.getsourcefile(self.fn)
+                            .replace("\\", "/")
+                            .replace(linux_friendly_os_cwd+'/', '')
+                            .replace('.py', '')
+                            .replace('/','.') +
+                            f":{self.fn.__name__}")
+        spec.binding.python.function = function_binding
+
+        sig = inspect.signature(self.fn)
+        
+        # If the function is a join tool, validate its signature matches the expected parameters. If not, raise error with details.
+        if self.kind == PythonToolKind.JOIN_TOOL:
+            _validate_join_tool_func(self.fn, sig, spec.name)
+
+        if not self.input_schema:
+            try:
+                input_schema_model: type[BaseModel] = create_schema_from_function(spec.name, self.fn, parse_docstring=True)
+            except:
+                logger.warning("Unable to properly parse parameter descriptions due to incorrectly formatted docstring. This may result in degraded agent performance. To fix this, please ensure the docstring conforms to Google's docstring format.")
+                input_schema_model: type[BaseModel] = create_schema_from_function(spec.name, self.fn, parse_docstring=False)
+            input_schema_json = input_schema_model.model_json_schema()
+            input_schema_json = dereference_refs(input_schema_json)
+
+            # Convert the input schema to a JsonSchemaObject
+            input_schema_obj = JsonSchemaObject(**input_schema_json)
+            input_schema_obj = _fix_optional(input_schema_obj)
+
+            spec.input_schema = ToolRequestBody(
+                type='object',
+                properties=input_schema_obj.properties or {},
+                required=input_schema_obj.required or []
+            )
+        else:
+            spec.input_schema = self.input_schema
+        
+        _validate_input_schema(spec.input_schema)
+
+        if not self.output_schema:
+            ret = sig.return_annotation
+            if ret != sig.empty:
+                _schema = dereference_refs(TypeAdapter(ret).json_schema())
+                if '$defs' in _schema:
+                    _schema.pop('$defs')
+                spec.output_schema = _fix_optional(ToolResponseBody(**_schema))
+            else:
+                spec.output_schema = ToolResponseBody()
+
+            if doc is not None and doc.returns is not None and doc.returns.description is not None:
+                spec.output_schema.description = doc.returns.description
+
+        else:
+            spec.output_schema = ToolResponseBody()
+        
+         # Validate the generated schema still conforms to the requirement for a join tool
+        if self.kind == PythonToolKind.JOIN_TOOL:
+            if not spec.is_custom_join_tool():
+                raise ValueError(f"Join tool '{spec.name}' does not conform to the expected join tool schema. Please ensure the input schema has the required fields: {JOIN_TOOL_PARAMS.keys()} and the output schema is a string.")
 
+        self._spec = spec
+        return spec
+    
     @staticmethod
     def from_spec(file: str) -> 'PythonTool':
         with open(file, 'r') as f:
@@ -42,10 +161,10 @@ class PythonTool(BaseTool):
             elif file.endswith('.json'):
                 spec = ToolSpec.model_validate(json.load(f))
             else:
-                raise ValueError('file must end in .json, .yaml, or .yml')
+                raise BadRequest('file must end in .json, .yaml, or .yml')
 
         if spec.binding.python is None:
-            raise ValueError('failed to load python tool as the tool had no python binding')
+            raise BadRequest('failed to load python tool as the tool had no python binding')
 
         [module, fn_name] = spec.binding.python.function.split(':')
         fn = getattr(importlib.import_module(module), fn_name)
@@ -147,92 +266,17 @@ def tool(
     """
     # inspiration: https://github.com/pydantic/pydantic/blob/main/pydantic/validate_call_decorator.py
     def _tool_decorator(fn):
-        if fn.__doc__ is not None:
-            doc = docstring_parser.parse(fn.__doc__)
-        else:
-            doc = None
-
-        _desc = description
-        if description is None and doc is not None:
-            _desc = doc.description
-
-        
-        spec = ToolSpec(
-            name=name or fn.__name__,
+        t = PythonTool(
+            fn=fn,
+            name=name,
+            description=description,
+            input_schema=input_schema,
+            output_schema=output_schema,
+            permission=permission,
+            expected_credentials=expected_credentials,
             display_name=display_name,
-            description=_desc,
-            permission=permission
+            kind=kind
         )
-
-        parsed_expected_credentials = []
-        if expected_credentials:
-            for credential in expected_credentials:
-                if isinstance(credential, ExpectedCredentials):
-                    parsed_expected_credentials.append(credential)
-                else:
-                    parsed_expected_credentials.append(ExpectedCredentials.model_validate(credential))
-        
-        t = PythonTool(fn=fn, spec=spec, expected_credentials=parsed_expected_credentials)
-        spec.binding = ToolBinding(python=PythonToolBinding(function=''))
-
-        linux_friendly_os_cwd = os.getcwd().replace("\\", "/")
-        function_binding = (inspect.getsourcefile(fn)
-                            .replace("\\", "/")
-                            .replace(linux_friendly_os_cwd+'/', '')
-                            .replace('.py', '')
-                            .replace('/','.') +
-                            f":{fn.__name__}")
-        spec.binding.python.function = function_binding
-
-        sig = inspect.signature(fn)
-        
-        # If the function is a join tool, validate its signature matches the expected parameters. If not, raise error with details.
-        if kind == PythonToolKind.JOIN_TOOL:
-            _validate_join_tool_func(fn, sig, spec.name)
-        
-        if not input_schema:
-            try:
-                input_schema_model: type[BaseModel] = create_schema_from_function(spec.name, fn, parse_docstring=True)
-            except:
-                logger.warning("Unable to properly parse parameter descriptions due to incorrectly formatted docstring. This may result in degraded agent performance. To fix this, please ensure the docstring conforms to Google's docstring format.")
-                input_schema_model: type[BaseModel] = create_schema_from_function(spec.name, fn, parse_docstring=False)
-            input_schema_json = input_schema_model.model_json_schema()
-            input_schema_json = dereference_refs(input_schema_json)
-
-            # Convert the input schema to a JsonSchemaObject
-            input_schema_obj = JsonSchemaObject(**input_schema_json)
-            input_schema_obj = _fix_optional(input_schema_obj)
-
-            spec.input_schema = ToolRequestBody(
-                type='object',
-                properties=input_schema_obj.properties or {},
-                required=input_schema_obj.required or []
-            )
-        else:
-            spec.input_schema = input_schema
-        
-        _validate_input_schema(spec.input_schema)
-
-        if not output_schema:
-            ret = sig.return_annotation
-            if ret != sig.empty:
-                _schema = dereference_refs(TypeAdapter(ret).json_schema())
-                if '$defs' in _schema:
-                    _schema.pop('$defs')
-                spec.output_schema = _fix_optional(ToolResponseBody(**_schema))
-            else:
-                spec.output_schema = ToolResponseBody()
-
-            if doc is not None and doc.returns is not None and doc.returns.description is not None:
-                spec.output_schema.description = doc.returns.description
-
-        else:
-            spec.output_schema = ToolResponseBody()
-        
-        # Validate the generated schema still conforms to the requirement for a join tool
-        if kind == PythonToolKind.JOIN_TOOL:
-            if not spec.is_custom_join_tool():
-                raise ValueError(f"Join tool '{spec.name}' does not conform to the expected join tool schema. Please ensure the input schema has the required fields: {JOIN_TOOL_PARAMS.keys()} and the output schema is a string.")
             
         _all_tools.append(t)
         return t

ibm_watsonx_orchestrate/agent_builder/tools/types.py

@@ -2,6 +2,7 @@ from enum import Enum
 from typing import List, Any, Dict, Literal, Optional, Union
 
 from pydantic import BaseModel, model_validator, ConfigDict, Field, AliasChoices
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 
 
 class ToolPermission(str, Enum):
@@ -74,19 +75,19 @@ class OpenApiSecurityScheme(BaseModel):
     @model_validator(mode='after')
     def validate_security_scheme(self) -> 'OpenApiSecurityScheme':
         if self.type == 'http' and self.scheme is None:
-            raise ValueError("'scheme' is required when type is 'http'")
+            raise BadRequest("'scheme' is required when type is 'http'")
 
         if self.type == 'oauth2' and self.flows is None:
-            raise ValueError("'flows' is required when type is 'oauth2'")
+            raise BadRequest("'flows' is required when type is 'oauth2'")
 
         if self.type == 'openIdConnect' and self.open_id_connect_url is None:
-            raise ValueError("'open_id_connect_url' is required when type is 'openIdConnect'")
+            raise BadRequest("'open_id_connect_url' is required when type is 'openIdConnect'")
 
         if self.type == 'apiKey':
             if self.name is None:
-                raise ValueError("'name' is required when type is 'apiKey'")
+                raise BadRequest("'name' is required when type is 'apiKey'")
             if self.in_field is None:
-                raise ValueError("'in_field' is required when type is 'apiKey'")
+                raise BadRequest("'in_field' is required when type is 'apiKey'")
 
         return self
 
@@ -96,9 +97,13 @@ HTTP_METHOD = Literal['GET', 'POST', 'PUT', 'PATCH', 'DELETE']
 class CallbackBinding(BaseModel):
     callback_url: str
     method: HTTP_METHOD
-    input_schema: ToolRequestBody
+    input_schema: Optional[ToolRequestBody] = None
     output_schema: ToolResponseBody
 
+class AcknowledgementBinding(BaseModel):
+    output_schema: ToolResponseBody
+
+
 class OpenApiToolBinding(BaseModel):
     http_method: HTTP_METHOD
     http_path: str
@@ -106,12 +111,13 @@ class OpenApiToolBinding(BaseModel):
     security: Optional[List[OpenApiSecurityScheme]] = None
     servers: Optional[List[str]] = None
     connection_id: str | None = None
-    callback: CallbackBinding = None
+    callback: Optional[CallbackBinding] = None
+    acknowledgement: Optional[AcknowledgementBinding] = None
 
     @model_validator(mode='after')
     def validate_openapi_tool_binding(self):
         if len(self.servers) != 1:
-            raise ValueError("OpenAPI definition must include exactly one server")
+            raise BadRequest("OpenAPI definition must include exactly one server")
         return self
 
 
@@ -129,7 +135,7 @@ class WxFlowsToolBinding(BaseModel):
     @model_validator(mode='after')
     def validate_security_scheme(self) -> 'WxFlowsToolBinding':
         if self.security.type != 'apiKey':
-            raise ValueError("'security' scheme must be of type 'apiKey'")
+            raise BadRequest("'security' scheme must be of type 'apiKey'")
         return self
 
 
@@ -173,9 +179,9 @@ class ToolBinding(BaseModel):
             self.flow is not None
         ]
         if sum(bindings) == 0:
-            raise ValueError("One binding must be set")
+            raise BadRequest("One binding must be set")
         if sum(bindings) > 1:
-            raise ValueError("Only one binding can be set")
+            raise BadRequest("Only one binding can be set")
         return self
 
 class ToolSpec(BaseModel):

ibm_watsonx_orchestrate/cli/commands/agents/agents_command.py

@@ -31,6 +31,13 @@ def agent_create(
         str,
         typer.Option("--name", "-n", help="Name of the agent you wish to create"),
     ],
+    description: Annotated[
+        str,
+        typer.Option(
+            "--description",
+            help="Description of the agent",
+        ),
+    ],
     title: Annotated[
         str,
         typer.Option("--title", "-t", help="Title of the agent you wish to create. Only needed for External and Assistant Agents"),
@@ -87,13 +94,6 @@ def agent_create(
         str,
         typer.Option("--app-id", help="Application ID for the agent"),
     ] = None,
-    description: Annotated[
-        str,
-        typer.Option(
-            "--description",
-            help="Description of the agent",
-        ),
-    ] = None,
     llm: Annotated[
         str,
         typer.Option(

ibm_watsonx_orchestrate/cli/commands/agents/agents_controller.py

@@ -29,6 +29,7 @@ from ibm_watsonx_orchestrate.client.agents.agent_client import AgentClient, Agen
 from ibm_watsonx_orchestrate.client.agents.external_agent_client import ExternalAgentClient
 from ibm_watsonx_orchestrate.client.agents.assistant_agent_client import AssistantAgentClient
 from ibm_watsonx_orchestrate.client.tools.tool_client import ToolClient
+from ibm_watsonx_orchestrate.utils.exceptions import BadRequest
 from ibm_watsonx_orchestrate.client.connections import get_connections_client
 from ibm_watsonx_orchestrate.client.knowledge_bases.knowledge_base_client import KnowledgeBaseClient
 
@@ -71,7 +72,7 @@ def create_agent_from_spec(file:str, kind:str) -> Agent | ExternalAgent | Assist
         case AgentKind.ASSISTANT:
             agent = AssistantAgent.from_spec(file)
         case _:
-            raise ValueError("'kind' must be either 'native' or 'external'")
+            raise BadRequest("'kind' must be either 'native' or 'external'")
 
     return agent
 
@@ -88,7 +89,7 @@ def parse_file(file: str) -> List[Agent | ExternalAgent | AssistantAgent]:
         agents = import_python_agent(file)
         return agents
     else:
-        raise ValueError("file must end in .json, .yaml, .yml or .py")
+        raise BadRequest("file must end in .json, .yaml, .yml or .py")
 
 def parse_create_native_args(name: str, kind: AgentKind, description: str | None, **args) -> dict:
     agent_details = {
@@ -768,7 +769,7 @@ class AgentsController:
                 for agent in native_agents:
                     agents_list.append(json.loads(agent.dumps_spec()))
 
-                rich.print(rich.json.JSON(json.dumps(agents_list, indent=4)))
+                rich.print_json(json.dumps(agents_list, indent=4))
             else:
                 native_table = rich.table.Table(
                     show_header=True, 
@@ -831,7 +832,7 @@ class AgentsController:
             if verbose:
                 for agent in external_agents:
                     external_agents_list.append(json.loads(agent.dumps_spec()))
-                rich.print(rich.json.JSON(json.dumps(external_agents_list, indent=4)))
+                rich.print_json(json.dumps(external_agents_list, indent=4))
             else:
                 external_table = rich.table.Table(
                     show_header=True, 
@@ -899,7 +900,7 @@ class AgentsController:
 
             if verbose:
                 for agent in assistant_agents:
-                    rich.print(agent.dumps_spec())
+                    rich.print_json(agent.dumps_spec())
             else:
                 assistants_table = rich.table.Table(
                     show_header=True, 
@@ -950,7 +951,7 @@ class AgentsController:
             elif kind == AgentKind.ASSISTANT:
                 client = self.get_assistant_client()
             else:
-                raise ValueError("'kind' must be 'native'")
+                raise BadRequest("'kind' must be 'native'")
 
             draft_agents = client.get_draft_by_name(name)
             if len(draft_agents) > 1:

ibm_watsonx_orchestrate/cli/commands/channels/types.py

@@ -13,7 +13,8 @@ class ChannelType(str, Enum):
 
     def __str__(self):
         return self.value
-    
+
+
 class RuntimeEnvironmentType(str, Enum):
     LOCAL = 'local'
     CPD = 'cpd'
@@ -22,6 +23,6 @@ class RuntimeEnvironmentType(str, Enum):
 
     def __str__(self):
         return self.value
-    
+
     def __repr__(self):
         return self.value

ibm_watsonx_orchestrate/cli/commands/channels/webchat/channels_webchat_controller.py

@@ -5,7 +5,6 @@ import sys
 
 from ibm_watsonx_orchestrate.cli.config import Config, ENV_WXO_URL_OPT, ENVIRONMENTS_SECTION_HEADER, CONTEXT_SECTION_HEADER, CONTEXT_ACTIVE_ENV_OPT, CHAT_UI_PORT
 from ibm_watsonx_orchestrate.cli.commands.channels.types import RuntimeEnvironmentType
-
 from ibm_watsonx_orchestrate.client.utils import is_local_dev, is_ibm_cloud_platform, get_environment, get_cpd_instance_id_from_url, is_saas_env, AUTH_CONFIG_FILE_FOLDER, AUTH_SECTION_HEADER, AUTH_MCSP_TOKEN_OPT, AUTH_CONFIG_FILE
 
 from ibm_watsonx_orchestrate.client.agents.agent_client import AgentClient
@@ -98,7 +97,7 @@ class ChannelsWebchatController:
         if target_env == 'draft' and is_saas == True:
             logger.error(f'For SAAS, please ensure this agent exists in a Live Environment')
             exit(1)
-             
+
         return filtered_environments[0].get("id")
 
     def get_tenant_id(self):

ibm_watsonx_orchestrate/cli/commands/connections/connections_command.py

@@ -201,6 +201,13 @@ def set_credentials_connection_command(
             help='For oauth_auth_client_credentials_flow, the client_secret to authenticate with'
         )
     ] = None,
+    send_via: Annotated[
+        str,
+        typer.Option(
+            '--send-via',
+            help='For oauth_auth_client_credentials_flow, how the token will be sent to the server. Defaults to using `header`'
+        )
+    ] = None,
     token_url: Annotated[
         str,
         typer.Option(
@@ -220,14 +227,14 @@ def set_credentials_connection_command(
         str,
         typer.Option(
             '--grant-type',
-            help='For oauth_auth_on_behalf_of_flow, the grant type used by the application token server'
+            help='For oauth_auth_on_behalf_of_flow and oauth_auth_client_credentials_flow, the grant type used by the application token server'
         )
     ] = None,
-    scopes: Annotated[
-        List[str],
+    scope: Annotated[
+        str,
         typer.Option(
-            '--scopes',
-            help='For oauth_auth_code_flow and oauth_auth_client_credentials_flow, the optional scopes used by the application token server'
+            '--scope',
+            help='For oauth_auth_code_flow and oauth_auth_client_credentials_flow, the optional scopes used by the application token server. Should be in the form of a space seperated string.'
         )
     ] = None,
     entries: Annotated[
@@ -247,10 +254,11 @@ def set_credentials_connection_command(
         api_key=api_key,
         client_id=client_id,
         client_secret=client_secret,
+        send_via=send_via,
         token_url=token_url,
         auth_url=auth_url,
         grant_type=grant_type,
-        scopes=scopes,
+        scope=scope,
         entries=entries
     )
 

ibm_watsonx_orchestrate/cli/commands/connections/connections_controller.py

@@ -160,13 +160,13 @@ def _validate_connection_params(type: ConnectionType, **args) -> None:
             f"Missing flags --token-url is required for type {type}"
         )
 
-
     if type == ConnectionType.OAUTH_ON_BEHALF_OF_FLOW and (
             args.get('grant_type') is None
     ):
         raise typer.BadParameter(
             f"Missing flags --grant-type is required for type {type}"
         )
+    
 
 def _parse_entry(entry: str) -> dict[str,str]:
     split_entry = entry.split('=')
@@ -197,15 +197,13 @@ def _get_credentials(type: ConnectionType, **kwargs):
                 client_id=kwargs.get("client_id"),
                 client_secret=kwargs.get("client_secret"),
                 token_url=kwargs.get("token_url"),
-                scopes=kwargs.get("scopes")
+                scope=kwargs.get("scope")
             )
         case ConnectionType.OAUTH2_CLIENT_CREDS:
-            return OAuth2ClientCredentials(
-                client_id=kwargs.get("client_id"),
-                client_secret=kwargs.get("client_secret"),
-                token_url=kwargs.get("token_url"),
-                scopes=kwargs.get("scopes")
-            )
+            # using filtered args as default values will not be set if 'None' is passed, causing validation errors
+            keys = ["client_id","client_secret","token_url","grant_type","send_via", "scope"]
+            filtered_args = { key_name: kwargs[key_name] for key_name in keys if kwargs.get(key_name) }
+            return OAuth2ClientCredentials(**filtered_args)
         # case ConnectionType.OAUTH2_IMPLICIT:
         #     return OAuth2ImplicitCredentials(
         #         authorization_url=kwargs.get("auth_url"),

ibm_watsonx_orchestrate/cli/commands/copilot/copilot_command.py

@@ -0,0 +1,65 @@
+import typer
+from typing_extensions import Annotated
+from pathlib import Path
+from ibm_watsonx_orchestrate.cli.commands.copilot.copilot_controller import prompt_tune, create_agent
+from ibm_watsonx_orchestrate.cli.commands.copilot.copilot_server_controller import start_server, stop_server
+
+copilot_app = typer.Typer(no_args_is_help=True)
+
+# Server Commands
+@copilot_app.command(name="start", help='Start the copilot server')
+def start_server_command(
+    user_env_file: str = typer.Option(
+        None,
+        "--env-file", "-e",
+        help="Path to a .env file that overrides default.env. Then environment variables override both."
+    )
+):
+    user_env_file_path = Path(user_env_file) if user_env_file else None
+
+    start_server(user_env_file_path=user_env_file_path)
+
+@copilot_app.command(name="stop", help='Stop the copilot server')
+def stop_server_command():
+    stop_server()
+
+# Functional Commands
+@copilot_app.command(name="prompt-tune", help='Tune the instructions of an Agent using IBM Conversational Prompt Engineering (CPE) to improve agent performance')
+def prompt_tume_command(
+    file: Annotated[
+        str,
+        typer.Option("--file", "-f", help="Path to agent spec file"),
+    ] = None,
+    output_file: Annotated[
+        str,
+        typer.Option("--output-file", "-o", help="Optional output file to avoid overwriting existing agent spec"),
+    ] = None,
+    dry_run_flag: Annotated[
+        bool,
+        typer.Option("--dry-run", help="Dry run will prevent the tuned content being saved and output the results to console"),
+    ] = False,
+    llm: Annotated[
+        str,
+        typer.Option("--llm", help="Select the agent LLM"),
+    ] = None,
+    samples: Annotated[
+        str,
+        typer.Option("--samples", "-s", help="Path to utterances sample file (txt file where each line is a utterance, or csv file with a single \"input\" column)"),
+    ] = None
+):
+    if file is None:
+        # create agent yaml from scratch
+        create_agent(
+            llm=llm,
+            output_file=output_file,
+            samples_file=samples,
+            dry_run_flag=dry_run_flag
+        )
+    else:
+        # improve existing agent instruction
+        prompt_tune(
+            agent_spec=file,
+            samples_file=samples,
+            output_file=output_file,
+            dry_run_flag=dry_run_flag,
+        )