sapiopycommons 2025.10.2a773__py3-none-any.whl → 2025.10.9a777__py3-none-any.whl

sapiopycommons/ai/{tool_service_base.py → agent_service_base.py}

@@ -17,6 +17,8 @@ from grpc import ServicerContext
 from sapiopylib.rest.User import SapioUser, ensure_logger_initialized
 from sapiopylib.rest.pojo.datatype.FieldDefinition import AbstractVeloxFieldDefinition
 
+from sapiopycommons.ai.external_credentials import ExternalCredentials
+from sapiopycommons.ai.protoapi.externalcredentials.external_credentials_pb2 import ExternalCredentialsPbo
 from sapiopycommons.ai.protoapi.fielddefinitions.fields_pb2 import FieldValueMapPbo, FieldValuePbo
 from sapiopycommons.ai.protoapi.fielddefinitions.velox_field_def_pb2 import VeloxFieldDefPbo, FieldTypePbo, \
     SelectionPropertiesPbo, IntegerPropertiesPbo, DoublePropertiesPbo, BooleanPropertiesPbo, StringPropertiesPbo, \
@@ -38,22 +40,22 @@ from sapiopycommons.general.aliases import FieldMap, FieldValue
 
 
 # FR-47422: Created classes.
-class SapioToolResult(ABC):
+class SapioAgentResult(ABC):
     """
-    A class representing a result from a Sapio tool. Instantiate one of the subclasses to create a result object.
+    A class representing a result from a Sapio agent. Instantiate one of the subclasses to create a result object.
     """
 
     @abstractmethod
     def to_proto(self) -> StepOutputBatchPbo | list[FieldValueMapPbo]:
         """
-        Convert this SapioToolResult object to a StepOutputBatchPbo or list of FieldValueMapPbo proto objects.
+        Convert this SapioAgentResult object to a StepOutputBatchPbo or list of FieldValueMapPbo proto objects.
         """
         pass
 
 
-class BinaryResult(SapioToolResult):
+class BinaryResult(SapioAgentResult):
     """
-    A class representing binary results from a Sapio tool.
+    A class representing binary results from a Sapio agent.
     """
     binary_data: list[bytes]
     content_type: str
@@ -66,7 +68,7 @@ class BinaryResult(SapioToolResult):
         :param binary_data: The binary data as a list of bytes.
         :param content_type: The content type of the data.
         :param file_extensions: A list of file extensions that this binary data can be saved as.
-        :param name: An optional identifying name for this result that will be accessible to the next tool.
+        :param name: An optional identifying name for this result that will be accessible to the next agent.
         """
         self.binary_data = binary_data
         self.content_type = content_type
@@ -83,9 +85,9 @@ class BinaryResult(SapioToolResult):
         )
 
 
-class CsvResult(SapioToolResult):
+class CsvResult(SapioAgentResult):
     """
-    A class representing CSV results from a Sapio tool.
+    A class representing CSV results from a Sapio agent.
     """
     csv_data: list[dict[str, Any]]
     content_type: str
@@ -98,7 +100,7 @@ class CsvResult(SapioToolResult):
         :param csv_data: The list of CSV data results, provided as a list of dictionaries of column name to value.
         :param content_type: The content type of the data.
         :param file_extensions: A list of file extensions that this binary data can be saved as.
-        :param name: An optional identifying name for this result that will be accessible to the next tool.
+        :param name: An optional identifying name for this result that will be accessible to the next agent.
         """
         self.csv_data = csv_data
         self.content_type = content_type
@@ -118,16 +120,16 @@ class CsvResult(SapioToolResult):
         )
 
 
-class FieldMapResult(SapioToolResult):
+class FieldMapResult(SapioAgentResult):
     """
-    A class representing field map results from a Sapio tool.
+    A class representing field map results from a Sapio agent.
     """
     field_maps: list[FieldMap]
 
     def __init__(self, field_maps: list[FieldMap]):
         """
         :param field_maps: A list of field maps, where each map is a dictionary of field names to values. Each entry
-            will create a new data record in the system, so long as the tool definition specifies an output data type
+            will create a new data record in the system, so long as the agent definition specifies an output data type
             name.
         """
         self.field_maps = field_maps
@@ -151,9 +153,9 @@ class FieldMapResult(SapioToolResult):
         return new_records
 
 
-class JsonResult(SapioToolResult):
+class JsonResult(SapioAgentResult):
     """
-    A class representing JSON results from a Sapio tool.
+    A class representing JSON results from a Sapio agent.
     """
     json_data: list[dict[str, Any]]
     content_type: str
@@ -167,7 +169,7 @@ class JsonResult(SapioToolResult):
             These entries must be able to be serialized to JSON using json.dumps().
         :param content_type: The content type of the data.
         :param file_extensions: A list of file extensions that this binary data can be saved as.
-        :param name: An optional identifying name for this result that will be accessible to the next tool.
+        :param name: An optional identifying name for this result that will be accessible to the next agent.
         """
         # Verify that the given json_data is actually a list of dictionaries.
         if not isinstance(json_data, list) or not all(isinstance(x, dict) for x in json_data):
@@ -187,9 +189,9 @@ class JsonResult(SapioToolResult):
         )
 
 
-class TextResult(SapioToolResult):
+class TextResult(SapioAgentResult):
     """
-    A class representing text results from a Sapio tool.
+    A class representing text results from a Sapio agent.
     """
     text_data: list[str]
     content_type: str
@@ -202,7 +204,7 @@ class TextResult(SapioToolResult):
         :param text_data: The text data as a list of strings.
         :param content_type: The content type of the data.
         :param file_extensions: A list of file extensions that this binary data can be saved as.
-        :param name: An optional identifying name for this result that will be accessible to the next tool.
+        :param name: An optional identifying name for this result that will be accessible to the next agent.
         """
         self.text_data = text_data
         self.content_type = content_type
@@ -219,24 +221,24 @@ class TextResult(SapioToolResult):
         )
 
 
-class ToolServiceBase(ToolServiceServicer, ABC):
+class AgentServiceBase(ToolServiceServicer, ABC):
     """
-    A base class for implementing a tool service. Subclasses should implement the register_tools method to register
-    their tools with the service.
+    A base class for implementing an agent service. Subclasses should implement the register_agents method to register
+    their agents with the service.
     """
     debug_mode: bool = False
 
     def GetToolDetails(self, request: ToolDetailsRequestPbo, context: ServicerContext) -> ToolDetailsResponsePbo:
         try:
-            # Get the tool details from the registered tools.
+            # Get the agent details from the registered agents.
             details: list[ToolDetailsPbo] = []
-            for tool in self.register_tools():
-                details.append(tool().to_pbo())
+            for agent in self.register_agents():
+                details.append(agent().to_pbo())
             if not details:
-                raise Exception("No tools registered with this service.")
-            return ToolDetailsResponsePbo(tool_framework_version=self.tool_version(), tool_details=details)
+                raise Exception("No agents registered with this service.")
+            return ToolDetailsResponsePbo(tool_framework_version=self.server_version(), tool_details=details)
         except Exception as e:
-            # Woe to you if you somehow cause an exception to be raised when just initializing your tools.
+            # Woe to you if you somehow cause an exception to be raised when just initializing your agents.
             # There's no way to log this.
             print(f"CRITICAL ERROR: {e}")
             print(traceback.format_exc())
@@ -246,7 +248,7 @@ class ToolServiceBase(ToolServiceServicer, ABC):
         try:
             # Convert the SapioConnectionInfo proto object to a SapioUser object.
             user = self._create_user(request.sapio_user)
-            # Get the tool results from the registered tool matching the request.
+            # Get the agent results from the registered agent matching the request.
             success, msg, results, logs = self.run(user, request, context)
             # Convert the results to protobuf objects.
             output_data: list[StepOutputBatchPbo] = []
@@ -262,7 +264,7 @@ class ToolServiceBase(ToolServiceServicer, ABC):
             return ProcessStepResponsePbo(status=status, status_message=msg, output=output_data, log=logs,
                                           new_records=new_records)
         except Exception as e:
-            # This try/except should never be needed, as the tool should handle its own exceptions, but better safe
+            # This try/except should never be needed, as the agent should handle its own exceptions, but better safe
             # than sorry.
             print(f"CRITICAL ERROR: {e}")
             print(traceback.format_exc())
@@ -294,88 +296,88 @@ class ToolServiceBase(ToolServiceServicer, ABC):
         return user
 
     @staticmethod
-    def tool_version() -> int:
+    def server_version() -> int:
         """
-        :return: The version of this set of tools.
+        :return: The version of this set of .
         """
         return 1
 
     @abstractmethod
-    def register_tools(self) -> list[type[ToolBase]]:
+    def register_agents(self) -> list[type[AgentBase]]:
         """
-        Register tool types with this service. Provided tools should implement the ToolBase class.
+        Register agent types with this service. Provided agents should implement the AgentBase class.
 
-        :return: A list of tools to register to this service.
+        :return: A list of agents to register to this service.
         """
         pass
 
     def run(self, user: SapioUser, request: ProcessStepRequestPbo, context: ServicerContext) \
-            -> tuple[bool, str, list[SapioToolResult], list[str]]:
+            -> tuple[bool, str, list[SapioAgentResult], list[str]]:
         """
-        Execute a tool from this service.
+        Execute an agent from this service.
 
         :param user: A user object that can be used to initialize manager classes using DataMgmtServer to query the
             system.
         :param request: The request object containing the input data.
         :param context: The gRPC context.
-        :return: Whether or not the tool succeeded, the status message, the results of the tool, and any logs
-            generated by the tool.
-        """
-        # Locate the tool named in the request.
-        find_tool: str = request.tool_name
-        registered_tools: dict[str, type[ToolBase]] = {t.name(): t for t in self.register_tools()}
-        if find_tool not in registered_tools:
-            # If the tool is not found, list all of the registered tools for this service so that the LLM can correct
-            # the tool it is requesting.
-            all_tool_names: str = "\n".join(registered_tools.keys())
-            msg: str = (f"Tool \"{find_tool}\" not found in the registered tools for this service. The registered "
-                        f"tools for this service are: \n{all_tool_names}")
+        :return: Whether or not the agent succeeded, the status message, the results of the agent, and any logs
+            generated by the agent.
+        """
+        # Locate the agent named in the request.
+        find_agent: str = request.tool_name
+        registered_agents: dict[str, type[AgentBase]] = {t.name(): t for t in self.register_agents()}
+        if find_agent not in registered_agents:
+            # If the agent is not found, list all of the registered agents for this service so that the LLM can correct
+            # the agent it is requesting.
+            all_agent_names: str = "\n".join(registered_agents.keys())
+            msg: str = (f"Agent \"{find_agent}\" not found in the registered agents for this service. The registered "
+                        f"agents for this service are: \n{all_agent_names}")
             return False, msg, [], []
 
-        # Instantiate the tool class.
-        tool: ToolBase = registered_tools[find_tool]()
+        # Instantiate the agent class.
+        agent: AgentBase = registered_agents[find_agent]()
         try:
-            # Setup the tool with details from the request.
-            tool.setup(user, request, context, self.debug_mode)
-            # Validate that the provided inputs match the tool's expected inputs.
+            # Setup the agent with details from the request.
+            agent.setup(user, request, context, self.debug_mode)
+            # Validate that the provided inputs match the agent's expected inputs.
             msg: str = ""
-            if len(request.input) != len(tool.input_configs):
-                msg = f"Expected {len(tool.input_configs)} inputs for this tool, but got {len(request.input)} instead."
+            if len(request.input) != len(agent.input_configs):
+                msg = f"Expected {len(agent.input_configs)} inputs for this agent, but got {len(request.input)} instead."
             else:
-                errors: list[str] = tool.validate_input()
+                errors: list[str] = agent.validate_input()
                 if errors:
                     msg = "\n".join(errors)
             # If there is no error message, then the inputs are valid.
             success: bool = not bool(msg)
             # If this is a dry run, then provide the fixed dry run output.
-            # Otherwise, if the inputs were successfully validated, then the tool is executed normally.
-            results: list[SapioToolResult] = []
+            # Otherwise, if the inputs were successfully validated, then the agent is executed normally.
+            results: list[SapioAgentResult] = []
             if request.dry_run:
-                results = tool.dry_run_output()
+                results = agent.dry_run_output()
             elif success:
-                results = tool.run(user)
-                # Update the status message to reflect the successful execution of the tool.
-                msg = f"{tool.name()} successfully completed."
-            return success, msg, results, tool.logs
+                results = agent.run(user)
+                # Update the status message to reflect the successful execution of the agent.
+                msg = f"{agent.name()} successfully completed."
+            return success, msg, results, agent.logs
         except Exception as e:
-            tool.log_exception("Exception occurred during tool execution.", e)
-            return False, str(e), [], tool.logs
+            agent.log_exception("Exception occurred during agent execution.", e)
+            return False, str(e), [], agent.logs
         finally:
-            # Clean up any temporary files created by the tool. If in debug mode, then log the files instead
+            # Clean up any temporary files created by the agent. If in debug mode, then log the files instead
             # so that they can be manually inspected.
             if self.debug_mode:
-                print("Temporary files/directories created during tool execution:")
-                for directory in tool.temp_data.directories:
+                print("Temporary files/directories created during agent execution:")
+                for directory in agent.temp_data.directories:
                     print(f"\tDirectory: {directory}")
-                for file in tool.temp_data.files:
+                for file in agent.temp_data.files:
                     print(f"\tFile: {file}")
             else:
-                tool.temp_data.cleanup()
+                agent.temp_data.cleanup()
 
 
-class ToolBase(ABC):
+class AgentBase(ABC):
     """
-    A base class for implementing a tool.
+    A base class for implementing an agent.
     """
     input_configs: list[ToolInputDetailsPbo]
     input_container_types: list[ContainerType]
@@ -398,9 +400,9 @@ class ToolBase(ABC):
     @abstractmethod
     def identifier(cls):
         """
-        :return: The unique identifier of the tool. This is used by the system to determine which tool should be
-            updated if a tool is re-imported. This should not be changed after the first time that a tool is imported,
-            otherwise a duplicate tool will be created.
+        :return: The unique identifier of the agent. This is used by the system to determine which agent should be
+            updated if an agent is re-imported. This should not be changed after the first time that an agent is
+            imported, otherwise a duplicate agent will be created.
         """
         pass
 
@@ -408,7 +410,7 @@ class ToolBase(ABC):
     @abstractmethod
     def name() -> str:
         """
-        :return: The display name of the tool. This should be unique across all tools in the service.
+        :return: The display name of the agent. This should be unique across all agents in the service.
         """
         pass
 
@@ -416,7 +418,7 @@ class ToolBase(ABC):
     @abstractmethod
     def category() -> str:
         """
-        :return: The category of the tool. This is used to group similar tools together in the plan manager.
+        :return: The category of the agent. This is used to group similar agents together in the plan manager.
         """
         pass
 
@@ -424,7 +426,7 @@ class ToolBase(ABC):
     @abstractmethod
     def description() -> str:
         """
-        :return: A description of the tool.
+        :return: A description of the agent.
         """
         pass
 
@@ -432,14 +434,14 @@ class ToolBase(ABC):
     @abstractmethod
     def citations() -> dict[str, str]:
         """
-        :return: Any citations or references for this tool, as a dictionary of citation name to URL.
+        :return: Any citations or references for this agent, as a dictionary of citation name to URL.
         """
         pass
 
     @staticmethod
     def data_type_name() -> str | None:
         """
-        :return: The name of the output data type of this tool, if applicable. When this tool returns
+        :return: The name of the output data type of this agent, if applicable. When this agent returns
             FieldMapResult objects in its run method, this name will be used to set the data type of the output data.
         """
         return None
@@ -447,8 +449,8 @@ class ToolBase(ABC):
     @staticmethod
     def license_flag() -> str | None:
         """
-        :return: The license flag for this tool. The system must have this license in order to use this tool.
-            If None, the tool is not license locked.
+        :return: The license flag for this agent. The system must have this license in order to use this agent.
+            If None, the agent is not license locked.
         """
         return None
 
@@ -460,19 +462,19 @@ class ToolBase(ABC):
         self.config_fields = []
         self.temp_data = TempFileHandler()
         self.logs = []
-        self.logger = logging.getLogger(f"ToolBase.{self.name()}")
+        self.logger = logging.getLogger(f"AgentBase.{self.name()}")
         ensure_logger_initialized(self.logger)
 
     def setup(self, user: SapioUser, request: ProcessStepRequestPbo, context: ServicerContext, debug_mode: bool) -> None:
         """
-        Setup the tool with the user, request, and context. This method can be overridden by subclasses to perform
+        Setup the agent with the user, request, and context. This method can be overridden by subclasses to perform
         additional setup.
 
         :param user: A user object that can be used to initialize manager classes using DataMgmtServer to query the
             system.
         :param request: The request object containing the input data.
         :param context: The gRPC context.
-        :param debug_mode: If true, the tool should run in debug mode, providing additional logging and not cleaning
+        :param debug_mode: If true, the agent should run in debug mode, providing additional logging and not cleaning
             up temporary files.
         """
         self.user = user
@@ -486,7 +488,7 @@ class ToolBase(ABC):
                   input_count: tuple[int, int] | None = None, is_paged: bool = False,
                   page_size: tuple[int, int] | None = None, max_request_bytes: int | None = None) -> None:
         """
-        Add an input configuration to the tool. This determines how many inputs this tool will accept in the plan
+        Add an input configuration to the agent. This determines how many inputs this agent will accept in the plan
         manager, as well as what those inputs are. The IO number of the input will be set to the current number of
         inputs. That is, the first time this is called, the IO number will be 0, the second time it is called, the IO
         number will be 1, and so on.
@@ -499,11 +501,11 @@ class ToolBase(ABC):
             JSON output may look. This does not need to be an entirely valid example, and should often be truncated for
             brevity. This must be provided for any container type other than BINARY.
         :param validation: An optional validation string for the input.
-        :param input_count: A tuple of the minimum and maximum number of inputs allowed for this tool.
+        :param input_count: A tuple of the minimum and maximum number of inputs allowed for this agent.
         :param is_paged: If true, this input will be paged. If false, this input will not be paged.
-        :param page_size: A tuple of the minimum and maximum page size for this tool. The input must be paged in order
+        :param page_size: A tuple of the minimum and maximum page size for this agent. The input must be paged in order
             for this to have an effect.
-        :param max_request_bytes: The maximum request size in bytes for this tool.
+        :param max_request_bytes: The maximum request size in bytes for this agent.
         """
         if container_type != ContainerType.BINARY and structure_example is None:
             raise ValueError("structure_example must be provided for inputs with a container_type other than BINARY.")
@@ -537,7 +539,7 @@ class ToolBase(ABC):
     def add_output(self, container_type: ContainerType, content_type: str, display_name: str, description: str,
                    testing_example: str | bytes, structure_example: str | bytes | None = None) -> None:
         """
-        Add an output configuration to the tool. This determines how many inputs this tool will accept in the plan
+        Add an output configuration to the agent. This determines how many inputs this agent will accept in the plan
         manager, as well as what those inputs are. The IO number of the output will be set to the current number of
         outputs. That is, the first time this is called, the IO number will be 0, the second time it is called, the IO
         number will be 1, and so on.
@@ -546,8 +548,8 @@ class ToolBase(ABC):
         :param content_type: The content type of the output.
         :param display_name: The display name of the output.
         :param description: The description of the output.
-        :param testing_example: An example of the input to be used when testing this tool in the system. This must be
-            an entirely valid example of what an output of this tool could look like so that it can be properly used
+        :param testing_example: An example of the input to be used when testing this agent in the system. This must be
+            an entirely valid example of what an output of this agent could look like so that it can be properly used
             to run tests with. The provided example may be a string, such as for representing JSON or CSV outputs,
             or bytes, such as for representing binary outputs like images or files.
         :param structure_example: An optional example of the structure of the input, such as how the structure of a
@@ -583,7 +585,7 @@ class ToolBase(ABC):
 
     def add_config_field(self, field: VeloxFieldDefPbo) -> None:
         """
-        Add a configuration field to the tool. This field will be used to configure the tool in the plan manager.
+        Add a configuration field to the agent. This field will be used to configure the agent in the plan manager.
 
         :param field: The configuration field details.
         """
@@ -591,7 +593,7 @@ class ToolBase(ABC):
 
     def add_config_field_def(self, field: AbstractVeloxFieldDefinition) -> None:
         """
-        Add a configuration field to the tool. This field will be used to configure the tool in the plan manager.
+        Add a configuration field to the agent. This field will be used to configure the agent in the plan manager.
 
         :param field: The configuration field details.
         """
@@ -600,7 +602,7 @@ class ToolBase(ABC):
     def add_boolean_config_field(self, field_name: str, display_name: str, description: str,
                                  default_value: bool | None = None, optional: bool = False) -> None:
         """
-        Add a boolean configuration field to the tool. This field will be used to configure the tool in the plan
+        Add a boolean configuration field to the agent. This field will be used to configure the agent in the plan
         manager.
 
         :param field_name: The name of the field.
@@ -625,7 +627,7 @@ class ToolBase(ABC):
                                 default_value: float | None = None, min_value: float = -10.**120,
                                 max_value: float = 10.**120, precision: int = 2, optional: bool = False) -> None:
         """
-        Add a double configuration field to the tool. This field will be used to configure the tool in the plan
+        Add a double configuration field to the agent. This field will be used to configure the agent in the plan
         manager.
 
         :param field_name: The name of the field.
@@ -656,7 +658,7 @@ class ToolBase(ABC):
                                  default_value: int | None = None, min_value: int = -2**31, max_value: int = 2**31-1,
                                  optional: bool = False) -> None:
         """
-        Add an integer configuration field to the tool. This field will be used to configure the tool in the plan
+        Add an integer configuration field to the agent. This field will be used to configure the agent in the plan
         manager.
 
         :param field_name: The name of the field.
@@ -685,7 +687,7 @@ class ToolBase(ABC):
                                 default_value: str | None = None, max_length: int = 1000, optional: bool = False,
                                 validation_regex: str | None = None, error_msg: str | None = None) -> None:
         """
-        Add a string configuration field to the tool. This field will be used to configure the tool in the plan
+        Add a string configuration field to the agent. This field will be used to configure the agent in the plan
         manager.
 
         :param field_name: The name of the field.
@@ -716,7 +718,7 @@ class ToolBase(ABC):
                               direct_edit: bool = False, optional: bool = False,
                               validation_regex: str | None = None, error_msg: str | None = None) -> None:
         """
-        Add a list configuration field to the tool. This field will be used to configure the tool in the plan
+        Add a list configuration field to the agent. This field will be used to configure the agent in the plan
         manager.
 
         :param field_name: The name of the field.
@@ -750,7 +752,7 @@ class ToolBase(ABC):
                                     direct_edit: bool = False, optional: bool = False,
                                     validation_regex: str | None = None, error_msg: str | None = None) -> None:
         """
-        Add a multi-select list configuration field to the tool. This field will be used to configure the tool in the
+        Add a multi-select list configuration field to the agent. This field will be used to configure the agent in the
         plan manager.
 
         :param field_name: The name of the field.
@@ -782,7 +784,7 @@ class ToolBase(ABC):
 
     def to_pbo(self) -> ToolDetailsPbo:
         """
-        :return: The ToolDetailsPbo proto object representing this tool.
+        :return: The ToolDetailsPbo proto object representing this agent.
         """
         return ToolDetailsPbo(
             import_id=self.identifier(),
@@ -800,7 +802,7 @@ class ToolBase(ABC):
     @abstractmethod
     def validate_input(self) -> list[str] | None:
         """
-        Validate the request given to this tool. If the request is validly formatted, this method should return None.
+        Validate the request given to this agent. If the request is validly formatted, this method should return None.
         If the request is not valid, this method should return an error message indicating what is wrong with the
         request.
 
@@ -816,18 +818,18 @@ class ToolBase(ABC):
         """
         pass
 
-    def dry_run_output(self) -> list[SapioToolResult]:
+    def dry_run_output(self) -> list[SapioAgentResult]:
         """
-        Provide fixed results for a dry run of this tool. This method should not perform any actual processing of the
-        request. It should only return example outputs that can be used to test the next tool in the plan.
+        Provide fixed results for a dry run of this agent. This method should not perform any actual processing of the
+        request. It should only return example outputs that can be used to test the next agent in the plan.
 
         The default implementation of this method looks at the testing_example field of each output configuration
-        and returns a SapioToolResult object based on the content type of the output.
+        and returns a SapioAgentResult object based on the content type of the output.
 
-        :return: A list of SapioToolResult objects containing example outputs for this tool. Each result in the list
-            corresponds to a separate output from the tool.
+        :return: A list of SapioAgentResult objects containing example outputs for this agent. Each result in the list
+            corresponds to a separate output from the agent.
         """
-        results: list[SapioToolResult] = []
+        results: list[SapioAgentResult] = []
         for output, container_type in zip(self.output_configs, self.output_container_types):
             config: ToolIoConfigBasePbo = output.base_config
             example: ExampleContainerPbo = config.testing_example
@@ -860,9 +862,9 @@ class ToolBase(ABC):
         return results
 
     @abstractmethod
-    def run(self, user: SapioUser) -> list[SapioToolResult]:
+    def run(self, user: SapioUser) -> list[SapioAgentResult]:
         """
-        Execute this tool.
+        Execute this agent.
 
         The request inputs can be accessed using the self.get_input_*() methods.
         The request settings can be accessed using the self.get_config_fields() method.
@@ -870,12 +872,44 @@ class ToolBase(ABC):
 
         :param user: A user object that can be used to initialize manager classes using DataMgmtServer to query the
             system.
-        :return: A list of SapioToolResult objects containing the response data. Each result in the list corresponds to
-            a separate output from the tool. Field map results do not appear as tool output in the plan manager, instead
-            appearing as records related to the plan step during the run.
+        :return: A list of SapioAgentResult objects containing the response data. Each result in the list corresponds to
+            a separate output from the agent. Field map results do not appear as agent output in the plan manager,
+            instead appearing as records related to the plan step during the run.
         """
         pass
 
+    def get_credentials(self, category: str = None, host: str = None) -> ExternalCredentials:
+        """
+        Get credentials for the given category and host.
+
+        :param category: The category of the credentials to retrieve.
+        :param host: The host for which to retrieve the credentials.
+        :return: An ExternalCredentials object containing the credentials for the given category and host.
+        """
+        # Remove leading/trailing whitespace
+        category = category.strip() if category else None
+        host = host.strip() if host else None
+
+        matching_creds: list[ExternalCredentialsPbo] = []
+        for cred in self.request.external_credential:
+            # Do case insensitive comparison
+            if category and cred.category.lower() != category.lower():
+                continue
+            if host:
+                # Parse the URL to get the host and compare
+                from urllib.parse import urlparse
+                parsed_url = urlparse(cred.url)
+                if parsed_url.hostname is None or parsed_url.hostname.lower() != host.lower():
+                    continue
+
+            matching_creds.append(cred)
+        if len(matching_creds) == 0:
+            raise ValueError(f"No credentials found for category '{category}' and host '{host}'.")
+        if len(matching_creds) > 1:
+            raise ValueError(f"Multiple credentials found for category '{category}' and host '{host}'.")
+
+        return ExternalCredentials(matching_creds[0])
+
     def call_subprocess(self,
                         args: str | bytes | PathLike[str] | PathLike[bytes] | Sequence[str | bytes | PathLike[str] | PathLike[bytes]],
                         cwd: str | bytes | PathLike[str] | PathLike[bytes] | None = None,
@@ -901,7 +935,7 @@ class ToolBase(ABC):
 
     def log_info(self, message: str) -> None:
         """
-        Log an info message for this tool. If verbose logging is enabled, this message will be included in the logs
+        Log an info message for this agent. If verbose logging is enabled, this message will be included in the logs
         returned to the caller. Empty/None inputs will not be logged.
 
         :param message: The message to log.
@@ -914,7 +948,7 @@ class ToolBase(ABC):
 
     def log_warning(self, message: str) -> None:
         """
-        Log a warning message for this tool. This message will be included in the logs returned to the caller.
+        Log a warning message for this agent. This message will be included in the logs returned to the caller.
         Empty/None inputs will not be logged.
 
         :param message: The message to log.
@@ -926,7 +960,7 @@ class ToolBase(ABC):
 
     def log_error(self, message: str) -> None:
         """
-        Log an error message for this tool. This message will be included in the logs returned to the caller.
+        Log an error message for this agent. This message will be included in the logs returned to the caller.
         Empty/None inputs will not be logged.
 
         :param message: The message to log.
@@ -938,7 +972,7 @@ class ToolBase(ABC):
 
     def log_exception(self, message: str, e: Exception) -> None:
         """
-        Log an exception for this tool. This message will be included in the logs returned to the caller.
+        Log an exception for this agent. This message will be included in the logs returned to the caller.
         Empty/None inputs will not be logged.
 
         :param message: The message to log.
@@ -953,7 +987,7 @@ class ToolBase(ABC):
         """
         Check if the input at the given index is marked as partial.
 
-        :param index: The index of the input to check. Defaults to 0. Used for tools that accept multiple inputs.
+        :param index: The index of the input to check. Defaults to 0. Used for agents that accept multiple inputs.
         :return: True if the input is marked as partial, False otherwise.
         """
         return self.request.input[index].is_partial
@@ -962,7 +996,7 @@ class ToolBase(ABC):
         """
         Get the name of the input from the request object.
 
-        :param index: The index of the input to parse. Defaults to 0. Used for tools that accept multiple inputs.
+        :param index: The index of the input to parse. Defaults to 0. Used for agents that accept multiple inputs.
         :return: The name of the input from the request object, or None if no name is set.
         """
         return self.request.input[index].item_container.container_name
@@ -971,7 +1005,7 @@ class ToolBase(ABC):
         """
         Get the content type of the input from the request object.
 
-        :param index: The index of the input to parse. Defaults to 0. Used for tools that accept multiple inputs.
+        :param index: The index of the input to parse. Defaults to 0. Used for agents that accept multiple inputs.
         :return: The content type of the input from the request object.
         """
         return self.request.input[index].item_container.content_type
@@ -980,7 +1014,7 @@ class ToolBase(ABC):
         """
         Get the binary data from the request object.
 
-        :param index: The index of the input to parse. Defaults to 0. Used for tools that accept multiple inputs.
+        :param index: The index of the input to parse. Defaults to 0. Used for agents that accept multiple inputs.
         :return: The binary data from the request object.
         """
         container: StepItemContainerPbo = self.request.input[index].item_container
@@ -992,7 +1026,7 @@ class ToolBase(ABC):
         """
         Parse the CSV data from the request object.
 
-        :param index: The index of the input to parse. Defaults to 0. Used for tools that accept multiple inputs.
+        :param index: The index of the input to parse. Defaults to 0. Used for agents that accept multiple inputs.
         :return: A tuple containing the header row and the data rows. The header row is a list of strings representing
             the column names, and the data rows are a list of dictionaries where each dictionary represents a row in the
             CSV with the column names as keys and the corresponding values as strings.
@@ -1013,7 +1047,7 @@ class ToolBase(ABC):
         """
         Parse the JSON data from the request object.
 
-        :param index: The index of the input to parse. Defaults to 0. Used for tools that accept multiple inputs.
+        :param index: The index of the input to parse. Defaults to 0. Used for agents that accept multiple inputs.
         :return: A list of parsed JSON objects, which are represented as dictionaries.
         """
         container: StepItemContainerPbo = self.request.input[index].item_container
@@ -1021,7 +1055,7 @@ class ToolBase(ABC):
             raise Exception(f"Input {index} does not contain a JSON container.")
         input_json: list[Any] = [json.loads(x) for x in container.json_container.items]
         # Verify that the given JSON actually is a list of dictionaries. If they aren't then the previous step provided
-        # bad input. Tools are enforced to result in a list of dictionaries when returning JSON data, so this is likely
+        # bad input. Agents are enforced to result in a list of dictionaries when returning JSON data, so this is likely
         # an error caused by a script or static input step.
         for i, entry in enumerate(input_json):
             if not isinstance(entry, dict):
@@ -1033,7 +1067,7 @@ class ToolBase(ABC):
         """
         Parse the text data from the request object.
 
-        :param index: The index of the input to parse. Defaults to 0. Used for tools that accept multiple inputs.
+        :param index: The index of the input to parse. Defaults to 0. Used for agents that accept multiple inputs.
         :return: A list of text data as strings.
         """
         container: StepItemContainerPbo = self.request.input[index].item_container
@@ -1043,7 +1077,7 @@ class ToolBase(ABC):
 
     def get_config_defs(self) -> dict[str, VeloxFieldDefPbo]:
         """
-        Get the config field definitions for this tool.
+        Get the config field definitions for this agent.
 
         :return: A dictionary of field definitions, where the keys are the field names and the values are the
             VeloxFieldDefPbo objects representing the field definitions.