ibm-watsonx-orchestrate 1.3.0__tar.gz → 1.4.2__tar.gz

{ibm_watsonx_orchestrate-1.3.0 → ibm_watsonx_orchestrate-1.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ibm-watsonx-orchestrate
-Version: 1.3.0
+Version: 1.4.2
 Summary: IBM watsonx.orchestrate SDK
 Author-email: IBM <support@ibm.com>
 License: MIT License
@@ -14,12 +14,15 @@ Requires-Dist: ibm-cloud-sdk-core>=3.22.0
 Requires-Dist: jsonref==1.1.0
 Requires-Dist: jsonschema<5.0.0,>=4.23.0
 Requires-Dist: langchain-community<1.0.0,>=0.3.12
+Requires-Dist: munch>=4.0.0
 Requires-Dist: numpy>=1.26.0
 Requires-Dist: packaging>=24.2
 Requires-Dist: pydantic<3.0.0,>=2.10.3
 Requires-Dist: pyjwt<3.0.0,>=2.10.1
 Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pytz>=2025.2
 Requires-Dist: pyyaml<7.0.0,>=6.0.2
+Requires-Dist: redis>=6.0.0
 Requires-Dist: requests>=2.32.0
 Requires-Dist: rich<14.0.0,>=13.9.4
 Requires-Dist: typer<1.0.0,>=0.15.1

{ibm_watsonx_orchestrate-1.3.0 → ibm_watsonx_orchestrate-1.4.2}/pyproject.toml

@@ -33,7 +33,10 @@ dependencies = [
     "requests>=2.32.0",
     "rich>=13.9.4,<14.0.0",
     "typer>=0.15.1,<1.0.0",
-    "urllib3>=2.2.3"
+    "urllib3>=2.2.3",
+    "munch>=4.0.0",
+    "pytz>=2025.2",
+    "redis>=6.0.0"
 ]
 
 [project.optional-dependencies]

{ibm_watsonx_orchestrate-1.3.0 → ibm_watsonx_orchestrate-1.4.2}/src/ibm_watsonx_orchestrate/__init__.py

@@ -5,7 +5,7 @@
 
 pkg_name = "ibm-watsonx-orchestrate"
 
-__version__ = "1.3.0"
+__version__ = "1.4.2"
 
 
 

{ibm_watsonx_orchestrate-1.3.0 → ibm_watsonx_orchestrate-1.4.2}/src/ibm_watsonx_orchestrate/agent_builder/agents/types.py

@@ -46,6 +46,7 @@ class BaseAgentSpec(BaseModel):
     kind: AgentKind
     id: Optional[Annotated[str, Field(json_schema_extra={"min_length_str": 1})]] = None
     name: Annotated[str, Field(json_schema_extra={"min_length_str":1})]
+    display_name: Annotated[Optional[str], Field(json_schema_extra={"min_length_str":1})] = None
     description: Annotated[str, Field(json_schema_extra={"min_length_str":1})]
 
     def dump_spec(self, file: str) -> None:
@@ -69,6 +70,7 @@ class BaseAgentSpec(BaseModel):
 class AgentStyle(str, Enum):
     DEFAULT = "default"
     REACT = "react"
+    PLANNER = "planner"
 
 class AgentSpec(BaseAgentSpec):
     model_config = ConfigDict(arbitrary_types_allowed=True)

{ibm_watsonx_orchestrate-1.3.0 → ibm_watsonx_orchestrate-1.4.2}/src/ibm_watsonx_orchestrate/agent_builder/knowledge_bases/types.py

@@ -3,8 +3,7 @@ from datetime import datetime
 from uuid import UUID
 from enum import Enum
 
-from pydantic import BaseModel, Field
-
+from pydantic import BaseModel, model_validator
 
 class SpecVersion(str, Enum):
     V1 = "v1"
@@ -213,6 +212,14 @@ class PatchKnowledgeBase(BaseModel):
     conversational_search_tool: Optional[ConversationalSearchConfig] = None  
     prioritize_built_in_index: Optional[bool] = None
     representation: Optional[KnowledgeBaseRepresentation] = None
+
+    @model_validator(mode="after")
+    def validate_fields(self):
+        if self.documents and self.conversational_search_tool and self.conversational_search_tool.index_config:
+            raise ValueError("Must not provide both \"documents\" or \"conversational_search_tool.index_config\"")
+        if self.conversational_search_tool and self.conversational_search_tool.index_config and len(self.conversational_search_tool.index_config) != 1:
+            raise ValueError(f"Must provide exactly one conversational_search_tool.index_config. Provided {len(self.conversational_search_tool.index_config)}.")
+        return self
     
 class KnowledgeBaseSpec(BaseModel):
     """Schema for a complete knowledge-base."""

ibm_watsonx_orchestrate-1.4.2/src/ibm_watsonx_orchestrate/agent_builder/toolkits/base_toolkit.py

@@ -0,0 +1,32 @@
+import json
+
+import yaml
+
+from .types import ToolkitSpec
+
+
+class BaseToolkit:
+    __toolkit_spec__: ToolkitSpec
+
+    def __init__(self, spec: ToolkitSpec):
+        self.__toolkit_spec__ = spec
+
+    def __call__(self, **kwargs):
+        pass
+
+    def dump_spec(self, file: str) -> None:
+        dumped = self.__toolkit_spec__.model_dump(mode='json', exclude_unset=True, exclude_none=True, by_alias=True)
+        with open(file, 'w') as f:
+            if file.endswith('.yaml') or file.endswith('.yml'):
+                yaml.dump(dumped, f)
+            elif file.endswith('.json'):
+                json.dump(dumped, f, indent=2)
+            else:
+                raise ValueError('file must end in .json, .yaml, or .yml')
+
+    def dumps_spec(self) -> str:
+        dumped = self.__toolkit_spec__.model_dump(mode='json', exclude_unset=True, exclude_none=True, by_alias=True)
+        return json.dumps(dumped, indent=2)
+
+    def __repr__(self):
+        return f"Toolkit(name='{self.__toolkit_spec__.name}', description='{self.__toolkit_spec__.description}')"

ibm_watsonx_orchestrate-1.4.2/src/ibm_watsonx_orchestrate/agent_builder/toolkits/types.py

@@ -0,0 +1,42 @@
+from typing import List, Dict, Optional
+from enum import Enum
+from pydantic import BaseModel, model_validator
+
+class ToolkitKind(str, Enum):
+    MCP = "mcp"
+
+class Language(str, Enum):
+    NODE = "node"
+    PYTHON ="python"
+
+class ToolkitSource(str, Enum):
+    FILES = "files"
+    PUBLIC_REGISTRY = "public-registry"
+
+
+
+class McpModel(BaseModel):
+    source: str
+    command: str
+    args: List[str]
+    tools: List[str]
+    connections: Dict[str, str]
+
+
+class ToolkitSpec(BaseModel):
+    id: str
+    tenant_id: str
+    name: str
+    description: Optional[str]
+    created_on: str
+    updated_at: str
+    created_by: str
+    created_by_username: str
+    tools: List[str] | None
+    mcp: McpModel
+
+    @model_validator(mode='after')
+    def validate_tools_and_mcp(self) -> 'ToolkitSpec':
+        if self.mcp.source not in {"files", "public-registry"}:
+            raise ValueError("MCP source must be either 'files' or 'public-registry'.")
+        return self

{ibm_watsonx_orchestrate-1.3.0 → ibm_watsonx_orchestrate-1.4.2}/src/ibm_watsonx_orchestrate/agent_builder/tools/openapi_tool.py

@@ -293,7 +293,7 @@ async def create_openapi_json_tool_from_uri(
         description=description,
         input_schema=input_schema,
         output_schema=output_schema,
-        app_id=app_id
+        connection_id=app_id
     )
 
 
@@ -302,6 +302,15 @@ async def create_openapi_json_tools_from_uri(
         connection_id: str = None
 ) -> List[OpenAPITool]:
     openapi_contents = await _get_openapi_spec_from_uri(openapi_uri)
+    tools: List[OpenAPITool] = await create_openapi_json_tools_from_content(openapi_contents, connection_id)
+
+    return tools
+
+async def create_openapi_json_tools_from_content(
+        openapi_contents: dict,
+        connection_id: str = None
+) -> List[OpenAPITool]:
+   
     tools: List[OpenAPITool] = []
 
     for path, methods in openapi_contents.get('paths', {}).items():

{ibm_watsonx_orchestrate-1.3.0 → ibm_watsonx_orchestrate-1.4.2}/src/ibm_watsonx_orchestrate/agent_builder/tools/python_tool.py

@@ -47,7 +47,7 @@ class PythonTool(BaseTool):
         return PythonTool(fn=fn, spec=spec)
 
     def __repr__(self):
-        return f"PythonTool(fn={self.__tool_spec__.binding.python.function}, name='{self.__tool_spec__.name}', description='{self.__tool_spec__.description}')"
+        return f"PythonTool(fn={self.__tool_spec__.binding.python.function}, name='{self.__tool_spec__.name}', display_name='{self.__tool_spec__.display_name or ''}', description='{self.__tool_spec__.description}')"
 
     def __str__(self):
         return self.__repr__()
@@ -99,7 +99,8 @@ def tool(
     input_schema: ToolRequestBody = None,
     output_schema: ToolResponseBody = None,
     permission: ToolPermission = ToolPermission.READ_ONLY,
-    expected_credentials: List[ExpectedCredentials] = None
+    expected_credentials: List[ExpectedCredentials] = None,
+    display_name: str = None
 ) -> Callable[[{__name__, __doc__}], PythonTool]:
     """
     Decorator to convert a python function into a callable tool.
@@ -125,6 +126,7 @@ def tool(
         
         spec = ToolSpec(
             name=name or fn.__name__,
+            display_name=display_name,
             description=_desc,
             permission=permission
         )

{ibm_watsonx_orchestrate-1.3.0 → ibm_watsonx_orchestrate-1.4.2}/src/ibm_watsonx_orchestrate/agent_builder/tools/types.py

@@ -137,7 +137,7 @@ class ClientSideToolBinding(BaseModel):
 class McpToolBinding(BaseModel):
     server_url: Optional[str] = None
     source: str
-    connections: Dict[str, str]
+    connections: Dict[str, str] | None
 
 class ToolBinding(BaseModel):
     openapi: OpenApiToolBinding = None
@@ -166,6 +166,7 @@ class ToolBinding(BaseModel):
 
 class ToolSpec(BaseModel):
     name: str
+    display_name: str | None = None
     description: str
     permission: ToolPermission
     input_schema: ToolRequestBody = None

{ibm_watsonx_orchestrate-1.3.0 → ibm_watsonx_orchestrate-1.4.2}/src/ibm_watsonx_orchestrate/cli/commands/agents/agents_command.py

@@ -190,3 +190,32 @@ def remove_agent(
 ):  
     agents_controller = AgentsController()
     agents_controller.remove_agent(name=name, kind=kind)
+
+@agents_app.command(name="export", help='Export an agent and its dependencies to a zip file or yaml')
+def export_agent(
+    name: Annotated[
+        str,
+        typer.Option("--name", "-n", help="Name of the agent you wish to export"),
+    ],
+    kind: Annotated[
+        AgentKind,
+        typer.Option("--kind", "-k", help="The kind of agent you wish to export"),
+    ],
+    output_file: Annotated[
+        str,
+        typer.Option(
+            "--output",
+            "-o",
+            help="Path to a where the file containing the exported data should be saved",
+        ),
+    ],
+    agent_only_flag: Annotated[
+        bool,
+        typer.Option(
+            "--agent-only",
+            help="Export only the yaml to the specified agent, excluding its dependencies",
+        ),
+    ]=False
+):  
+    agents_controller = AgentsController()
+    agents_controller.export_agent(name=name, kind=kind, output_path=output_file, agent_only_flag=agent_only_flag)

{ibm_watsonx_orchestrate-1.3.0 → ibm_watsonx_orchestrate-1.4.2}/src/ibm_watsonx_orchestrate/cli/commands/agents/agents_controller.py

@@ -4,13 +4,15 @@ import rich
 import requests
 import importlib
 import inspect
+import zipfile
 import sys
+import io
 import logging
 from pathlib import Path
 from copy import deepcopy
 
 from typing import Iterable, List
-from ibm_watsonx_orchestrate.cli.commands.tools.tools_controller import import_python_tool
+from ibm_watsonx_orchestrate.cli.commands.tools.tools_controller import import_python_tool, ToolsController
 from ibm_watsonx_orchestrate.cli.commands.knowledge_bases.knowledge_bases_controller import import_python_knowledge_base
 
 from ibm_watsonx_orchestrate.agent_builder.agents import (
@@ -28,6 +30,7 @@ from ibm_watsonx_orchestrate.client.connections import get_connections_client
 from ibm_watsonx_orchestrate.client.knowledge_bases.knowledge_base_client import KnowledgeBaseClient
 
 from ibm_watsonx_orchestrate.client.utils import instantiate_client
+from ibm_watsonx_orchestrate.utils.utils import check_file_in_zip
 
 logger = logging.getLogger(__name__)
 
@@ -142,10 +145,29 @@ def get_conn_id_from_app_id(app_id: str) -> str:
     connections_client = get_connections_client()
     connection = connections_client.get_draft_by_app_id(app_id=app_id)
     if not connection:
-        logger.error(f"No connection exits with the app-id '{app_id}'")
+        logger.error(f"No connection exists with the app-id '{app_id}'")
         exit(1)
     return connection.connection_id
 
+def get_app_id_from_conn_id(conn_id: str) -> str:
+    connections_client = get_connections_client()
+    app_id = connections_client.get_draft_by_id(conn_id=conn_id)
+    if not app_id or app_id == conn_id:
+        logger.error(f"No connection exists with the connection id '{conn_id}'")
+        exit(1)
+    return app_id
+
+def get_agent_details(name: str, client: AgentClient | ExternalAgentClient | AssistantAgentClient) -> dict:
+    agent_specs = client.get_draft_by_name(name)
+    if len(agent_specs) > 1:
+            logger.error(f"Multiple agents with the name '{name}' found. Failed to get agent")
+            sys.exit(1)
+    if len(agent_specs) == 0:
+            logger.error(f"No agents with the name '{name}' found. Failed to get agent")
+            sys.exit(1)
+
+    return agent_specs[0]
+
 class AgentsController:
     def __init__(self):
         self.native_client = None
@@ -227,6 +249,7 @@ class AgentsController:
         matching_external_agents = external_client.get_drafts_by_names(deref_agent.collaborators)
         matching_assistant_agents = assistant_client.get_drafts_by_names(deref_agent.collaborators)
         matching_agents = matching_native_agents + matching_external_agents + matching_assistant_agents
+
         name_id_lookup = {}
         for a in matching_agents:
             if a.get("name") in name_id_lookup:
@@ -245,6 +268,35 @@ class AgentsController:
 
         return deref_agent
     
+    def reference_collaborators(self, agent: Agent) -> Agent:
+        native_client = self.get_native_client()
+        external_client = self.get_external_client()
+        assistant_client = self.get_assistant_client()
+
+        ref_agent = deepcopy(agent)
+        matching_native_agents = native_client.get_drafts_by_ids(ref_agent.collaborators)
+        matching_external_agents = external_client.get_drafts_by_ids(ref_agent.collaborators)
+        matching_assistant_agents = assistant_client.get_drafts_by_ids(ref_agent.collaborators)
+        matching_agents = matching_native_agents + matching_external_agents + matching_assistant_agents
+        
+        id_name_lookup = {}
+        for a in matching_agents:
+            if a.get("id") in id_name_lookup:
+                logger.error(f"Duplicate draft entries for collaborator '{a.get('id')}'")
+                sys.exit(1)
+            id_name_lookup[a.get("id")] = a.get("name")
+
+        ref_collaborators = []
+        for id in agent.collaborators:
+            name = id_name_lookup.get(id)
+            if not name:
+                logger.error(f"Failed to find collaborator. No agents found with the id '{id}'")
+                sys.exit(1)
+            ref_collaborators.append(name)
+        ref_agent.collaborators = ref_collaborators
+
+        return ref_agent
+    
     def dereference_tools(self, agent: Agent) -> Agent:
         tool_client = self.get_tool_client()
 
@@ -254,7 +306,7 @@ class AgentsController:
         name_id_lookup = {}
         for tool in matching_tools:
             if tool.get("name") in name_id_lookup:
-                logger.error(f"Duplicate draft entries for tol '{tool.get('name')}'")
+                logger.error(f"Duplicate draft entries for tool '{tool.get('name')}'")
                 sys.exit(1)
             name_id_lookup[tool.get("name")] = tool.get("id")
         
@@ -269,6 +321,30 @@ class AgentsController:
 
         return deref_agent
     
+    def reference_tools(self, agent: Agent) -> Agent:
+        tool_client = self.get_tool_client()
+
+        ref_agent = deepcopy(agent)
+        matching_tools = tool_client.get_drafts_by_ids(ref_agent.tools)
+
+        id_name_lookup = {}
+        for tool in matching_tools:
+            if tool.get("id") in id_name_lookup:
+                logger.error(f"Duplicate draft entries for tool '{tool.get('id')}'")
+                sys.exit(1)
+            id_name_lookup[tool.get("id")] = tool.get("name")
+        
+        ref_tools = []
+        for id in agent.tools:
+            name = id_name_lookup[id]
+            if not name:
+                logger.error(f"Failed to find tool. No tools found with the id '{id}'")
+                sys.exit(1)
+            ref_tools.append(name)
+        ref_agent.tools = ref_tools
+
+        return ref_agent
+    
     def dereference_knowledge_bases(self, agent: Agent) -> Agent:
         client = self.get_knowledge_base_client()
 
@@ -293,6 +369,22 @@ class AgentsController:
 
         return deref_agent
     
+    def reference_knowledge_bases(self, agent: Agent) -> Agent:
+        client = self.get_knowledge_base_client()
+
+        ref_agent = deepcopy(agent)
+        
+        ref_knowledge_bases = []
+        for id in agent.knowledge_base:
+            matching_knowledge_base = client.get_by_id(id)
+            name = matching_knowledge_base.get("name")
+            if not name:
+                logger.error(f"Failed to find knowledge base. No knowledge base found with the id '{id}'")
+                sys.exit(1)
+            ref_knowledge_bases.append(name)
+        ref_agent.knowledge_base = ref_knowledge_bases
+        return ref_agent
+    
     @staticmethod
     def dereference_app_id(agent: ExternalAgent | AssistantAgent) -> ExternalAgent | AssistantAgent:
         if agent.kind == AgentKind.EXTERNAL:
@@ -301,6 +393,17 @@ class AgentsController:
             agent.config.connection_id = get_conn_id_from_app_id(agent.config.app_id)
 
         return agent
+    
+    @staticmethod
+    def reference_app_id(agent: ExternalAgent | AssistantAgent) -> ExternalAgent | AssistantAgent:
+        if agent.kind == AgentKind.EXTERNAL:
+            agent.app_id = get_app_id_from_conn_id(agent.connection_id)
+            agent.connection_id = None
+        else:
+            agent.config.app_id = get_app_id_from_conn_id(agent.config.connection_id)
+            agent.config.connection_id = None
+
+        return agent
 
 
     def dereference_native_agent_dependencies(self, agent: Agent) -> Agent:
@@ -313,6 +416,16 @@ class AgentsController:
 
         return agent
     
+    def reference_native_agent_dependencies(self, agent: Agent) -> Agent:
+        if agent.collaborators and len(agent.collaborators):
+            agent = self.reference_collaborators(agent)
+        if agent.tools and len(agent.tools):
+            agent = self.reference_tools(agent)
+        if agent.knowledge_base and len(agent.knowledge_base):
+            agent = self.reference_knowledge_bases(agent)
+
+        return agent
+    
     def dereference_external_or_assistant_agent_dependencies(self, agent: ExternalAgent | AssistantAgent) -> ExternalAgent | AssistantAgent: 
         agent_dict = agent.model_dump()
 
@@ -320,13 +433,28 @@ class AgentsController:
             agent = self.dereference_app_id(agent)
 
         return agent
-                
-    def dereference_agent_dependencies(self, agent: Agent ) -> Agent | ExternalAgent | AssistantAgent:
+
+    def reference_external_or_assistant_agent_dependencies(self, agent: ExternalAgent | AssistantAgent) -> ExternalAgent | AssistantAgent: 
+        agent_dict = agent.model_dump()
+
+        if agent_dict.get("connection_id") or agent.config.model_dump().get("connection_id"):
+            agent = self.reference_app_id(agent)
+
+        return agent
+    
+    # Convert all names used in an agent to the corresponding ids
+    def dereference_agent_dependencies(self, agent: Agent | ExternalAgent | AssistantAgent ) -> Agent | ExternalAgent | AssistantAgent:
         if isinstance(agent, Agent):
             return self.dereference_native_agent_dependencies(agent)
         if isinstance(agent, ExternalAgent) or isinstance(agent, AssistantAgent):
             return self.dereference_external_or_assistant_agent_dependencies(agent)
-        
+    
+    # Convert all ids used in an agent to the corresponding names
+    def reference_agent_dependencies(self, agent: Agent | ExternalAgent | AssistantAgent ) -> Agent | ExternalAgent | AssistantAgent:
+        if isinstance(agent, Agent):
+            return self.reference_native_agent_dependencies(agent)
+        if isinstance(agent, ExternalAgent) or isinstance(agent, AssistantAgent):
+            return self.reference_external_or_assistant_agent_dependencies(agent)
 
     def publish_or_update_agents(
         self, agents: Iterable[Agent]
@@ -368,13 +496,13 @@ class AgentsController:
 
     def publish_agent(self, agent: Agent, **kwargs) -> None:
         if isinstance(agent, Agent):
-            self.get_native_client().create(agent.model_dump())
+            self.get_native_client().create(agent.model_dump(exclude_none=True))
             logger.info(f"Agent '{agent.name}' imported successfully")
         if isinstance(agent, ExternalAgent):
-            self.get_external_client().create(agent.model_dump())
+            self.get_external_client().create(agent.model_dump(exclude_none=True))
             logger.info(f"External Agent '{agent.name}' imported successfully")
         if isinstance(agent, AssistantAgent):
-            self.get_assistant_client().create(agent.model_dump(by_alias=True))
+            self.get_assistant_client().create(agent.model_dump(exclude_none=True, by_alias=True))
             logger.info(f"Assistant Agent '{agent.name}' imported successfully")
 
     def update_agent(
@@ -382,15 +510,15 @@ class AgentsController:
     ) -> None:
         if isinstance(agent, Agent):
             logger.info(f"Existing Agent '{agent.name}' found. Updating...")
-            self.get_native_client().update(agent_id, agent.model_dump())
+            self.get_native_client().update(agent_id, agent.model_dump(exclude_none=True))
             logger.info(f"Agent '{agent.name}' updated successfully")
         if isinstance(agent, ExternalAgent):
             logger.info(f"Existing External Agent '{agent.name}' found. Updating...")
-            self.get_external_client().update(agent_id, agent.model_dump())
+            self.get_external_client().update(agent_id, agent.model_dump(exclude_none=True))
             logger.info(f"External Agent '{agent.name}' updated successfully")
         if isinstance(agent, AssistantAgent):
             logger.info(f"Existing Assistant Agent '{agent.name}' found. Updating...")
-            self.get_assistant_client().update(agent_id, agent.model_dump(by_alias=True))
+            self.get_assistant_client().update(agent_id, agent.model_dump(exclude_none=True, by_alias=True))
             logger.info(f"Assistant Agent '{agent.name}' updated successfully")
 
     @staticmethod
@@ -659,4 +787,135 @@ class AgentsController:
             except requests.HTTPError as e:
                 logger.error(e.response.text)
                 exit(1)
+    
+    def get_spec_file_content(self, agent: Agent | ExternalAgent | AssistantAgent):
+        ref_agent = self.reference_agent_dependencies(agent)
+        agent_spec = ref_agent.model_dump(mode='json', exclude_none=True)
+        return agent_spec
+
+    def get_agent(self, name: str, kind: AgentKind) -> Agent | ExternalAgent | AssistantAgent:
+        match kind:
+            case AgentKind.NATIVE:
+                client = self.get_native_client()
+                agent_details = get_agent_details(name=name, client=client)
+                agent = Agent.model_validate(agent_details)
+            case AgentKind.EXTERNAL:
+                client = self.get_external_client()
+                agent_details = get_agent_details(name=name, client=client)
+                agent = ExternalAgent.model_validate(agent_details)
+            case AgentKind.ASSISTANT:
+                client = self.get_assistant_client()
+                agent_details = get_agent_details(name=name, client=client)
+                agent = AssistantAgent.model_validate(agent_details)
+        
+        return agent
+    
+    def get_agent_by_id(self, id: str) -> Agent | ExternalAgent | AssistantAgent:
+        native_client = self.get_native_client()
+        external_client = self.get_external_client()
+        assistant_client = self.get_assistant_client()
+
+        native_result = native_client.get_draft_by_id(id)
+        external_result = external_client.get_draft_by_id(id)
+        assistant_result = assistant_client.get_draft_by_id(id)
+
+        if native_result:
+            return Agent.model_validate(native_result)
+        if external_result:
+            return ExternalAgent.model_validate(external_result)
+        if assistant_result:
+            return AssistantAgent.model_validate(assistant_result)
+        
+
+    def export_agent(self, name: str, kind: AgentKind, output_path: str, agent_only_flag: bool=False, zip_file_out: zipfile.ZipFile | None = None) -> None:
+    
+        output_file = Path(output_path)
+        output_file_extension = output_file.suffix
+        output_file_name = output_file.stem
+        if not agent_only_flag and output_file_extension != ".zip":
+            logger.error(f"Output file must end with the extension '.zip'. Provided file '{output_path}' ends with '{output_file_extension}'")
+            sys.exit(1)
+        elif agent_only_flag and (output_file_extension != ".yaml" and output_file_extension != ".yml"):
+            logger.error(f"Output file must end with the extension '.yaml' or '.yml'. Provided file '{output_path}' ends with '{output_file_extension}'")
+            sys.exit(1)
+        
+        agent = self.get_agent(name, kind)
+        agent_spec_file_content = self.get_spec_file_content(agent)
+        
+        agent_spec_file_content.pop("hidden", None)
+        agent_spec_file_content.pop("id", None)
+        agent_spec_file_content["spec_version"] = SpecVersion.V1.value
+
+        if agent_only_flag:
+            logger.info(f"Exported agent definition for '{name}' to '{output_path}'")
+            with open(output_path, 'w') as outfile:
+                yaml.dump(agent_spec_file_content, outfile, sort_keys=False, default_flow_style=False)
+            return
+        
+        close_file_flag = False
+        if zip_file_out is None:
+            close_file_flag = True
+            zip_file_out = zipfile.ZipFile(output_path, "w")
+
+        logger.info(f"Exporting agent definition for '{name}'")
+        
+        agent_spec_yaml = yaml.dump(agent_spec_file_content, sort_keys=False, default_flow_style=False)
+        agent_spec_yaml_bytes = agent_spec_yaml.encode("utf-8")
+        agent_spec_yaml_file = io.BytesIO(agent_spec_yaml_bytes)
+
+        # Skip processing an agent if its already been saved
+        agent_file_path = f"{output_file_name}/agents/{agent_spec_file_content.get('kind', 'unknown')}/{agent_spec_file_content.get('name')}.yaml"
+        if check_file_in_zip(file_path=agent_file_path, zip_file=zip_file_out):
+            logger.warning(f"Skipping {agent_spec_file_content.get('name')}, agent with that name already exists in the output folder")
+            if close_file_flag:
+                zip_file_out.close()
+            return
+        
+        zip_file_out.writestr(
+            agent_file_path,
+            agent_spec_yaml_file.getvalue()
+        )
+
+        tools_contoller = ToolsController()
+        for tool_name in agent_spec_file_content.get("tools", []):
+
+            base_tool_file_path = f"{output_file_name}/tools/{tool_name}/"
+            if check_file_in_zip(file_path=base_tool_file_path, zip_file=zip_file_out):
+                continue
+            
+            logger.info(f"Exporting tool '{tool_name}'")
+            tool_artifact_bytes = tools_contoller.download_tool(tool_name)
+            if not tool_artifact_bytes:
+                continue
+            
+            with zipfile.ZipFile(io.BytesIO(tool_artifact_bytes), "r") as zip_file_in:
+                for item in zip_file_in.infolist():
+                    buffer = zip_file_in.read(item.filename)
+                    if (item.filename != 'bundle-format'):
+                        zip_file_out.writestr(
+                            f"{base_tool_file_path}{item.filename}",
+                            buffer
+                        )
+        
+        for kb_name in agent_spec_file_content.get("knowledge_base", []):
+            logger.warning(f"Skipping {kb_name}, knowledge_bases are currently unsupported by export")
+        
+        if kind == AgentKind.NATIVE:
+            for collaborator_id in agent.collaborators:
+                collaborator = self.get_agent_by_id(collaborator_id)
+
+                if not collaborator:
+                    logger.warning(f"Skipping {collaborator_id}, no agent with id {collaborator_id} found")
+                    continue
+                
+                self.export_agent(
+                    name=collaborator.name,
+                    kind=collaborator.kind,
+                    output_path=output_path,
+                    agent_only_flag=False,
+                    zip_file_out=zip_file_out)
+        
+        if close_file_flag:
+            logger.info(f"Successfully wrote agents and tools to '{output_path}'")
+            zip_file_out.close()