4.3.1 Create an Internal Tool Configuration

Create an internal tool configuration to register an internal MicroTx Workflows tool, so that you can reuse the tool in agentic workflows and AI agent profiles.

Each tool configuration stores the runtime settings needed to invoke a tool, such as the tool's endpoint URL, credentials, profile references, or tool-specific options.

Prerequisites

Before you begin creating a tool configuration, ensure the required dependencies for that category are available.

  • For Database tool, ensure that either a database profile with the required details already exists or create a new one. You will need to provide the name of the database profile while creating a database tool. See Create a Database Profile.
  • For Workflow tool, identify the list of allowed workflow names.
  • For Agent tool, define the target agent execution settings in an Agent profile. See Create an Agent Profile.
  • For RAG search tool, prepare the required RAG retrieval settings.
  • For API (HTTP) tool, ensure that the endpoint URL and required authentication details are available. For example, API key.
To create a tool configuration:
  1. Open the navigation menu and click Connectors.
  2. Click Internal Tools.

    The Internal Tools list page opens. All the internal tool configurations that you have defined are displayed in a table.

  3. Click add a new building block.
    The New Tools Config dialog box appears.
  4. In the Name box, enter a unique and descriptive name to identify this tool configuration in workflows and tasks. The name can be up to 128-characters long. Use only letters, numbers, underscores (_), and hyphens (-). Spaces and other special characters are not supported.
  5. Optional. In the Description box, provide a brief summary about the intended use of the tool configuration or any relevant details that will help others understand its purpose.
  6. In the Category drop-down list, select one of the following options to specify an appropriate category for the tool.
    • API: Select this option when an agent must call external HTTP endpoints.
      • Type: Select HTTP.
      • URL: Optional. Enter the endpoint or base URL required to access this tool. This is typically the address used for API calls or service requests.

      • API Key: Optional. If the tool requires authorization using an API key, provide the bearer token value. MicroTx Workflows encrypts and stores the provided API key. Ensure that you follow your organization's security guidelines for handling and storing sensitive credentials.

    • Database: Select this option when agent must run database operations. In the Database Profile drop-down list, select a database profile that you have created earlier to securely provide the database connection details.
    • Agent: Select this option when one agent or tool should invoke another agent profile. This is mainly used by conversational agents to invoke sub-agents as part of agent chat. In the Agent Profile drop-down list, select the target agent profile that you have created earlier. In the Input Data (JSON) field, provide the input parameters if the target agent requires any.
    • Workflow: Select this option when the tool should start the selected workflows. This is mainly used by conversational agents to invoke workflows through the tool. In the Workflow Name field, select the names of the workflows.
    • DateTime
    • Calculator
    • File: When you select this option, files are selected from the local file storage of MicroTx Workflows. The default base path of the local file storage is the value specified in the conductor.connector.storage-path property in the application.properties file.
    • RAG search: Select this option when agent must retrieve knowledge from vector or RAG store. Provide the following information for the various parameters to configure the RAG Retrieval Tool:
      • RAG Type: Optional. Select the retrieval mode. Supported values are NAIVE and ADVANCED. The default value is NAIVE. The advanced mode rewrites the query and compresses retrieved documents before generating the response.
      • Database Profile: Mandatory. Select the database profile for the Oracle AI Database instance that contains the vector table.
      • LLM Profile: Mandatory. Select the LLM definition used to generate the final response.
      • LLM Model: Optional. Select the model to use to generate response.
      • Embedding Model Profile: Mandatory. Select the LLM definition that contains the embedding model. Use the same embedding profile that was used to ingest the data, unless the new model produces compatible embeddings.
      • Embedding Model: Optional. Select the embedding model used to convert the query into a vector. This should match the model used during ingestion.
      • Table Name: Required. Enter the table name that contains the vector embeddings.
      • Base Filter (JSON): Optional. Provide a JSON metadata filter that is always applied when the RAG Retrieval tool searches the vector table. Use a base filter to enforce a fixed retrieval boundary for the tool, such as a tenant, project, approved content set, or active records.

        Note:

        When an agent calls the tool with an additional filter, MicroTx Workflows combines the base filter and the agent-supplied filter with logical and. The agent cannot use its filter to remove or override the base filter. For example, configure this base filter to restrict the tool to active content for one project: 
        {
  "op": "and",
  "filters": [
    {
      "field": "project_id",
      "op": "eq",
      "value": "project-123"
    },
    {
      "field": "active",
      "op": "eq",
      "value": true
    }
  ]
}
        The tool exposes a semantic search operation and a filtered semantic search operation. When filtering is required, agents must pass the filter as a JSON object in the documented format. Tool descriptions instruct agents not to use SQL or raw filter expressions.
      • Temperature: Optional.
      • Max Tokens: Optional.
      • TopK (LLM): Optional. Controls token sampling for the response generation model. In JSON, use top_k. The default value is 40.
      • Dimensions: Optional. Enter the vector dimension count. The default value is 512. This value must match the vector table definition and the embeddings generated during ingestion.
      • Index Type: Optional. Select the vector index type. Use the same index configuration as the vector table. Select HNSW for Hierarchical Navigable Small World (HNSW), IVF for Inverted File Flat (IVF), or NONE. The default value is HNSW.
      • Distance Type: Optional. Select the distance metric used for vector similarity search. Use the same distance metric used during ingestion. Supported values are COSINE, DOT, EUCLIDEAN, MANHATTAN, and EUCLIDEAN_SQUARED. The default value is COSINE.
      • TopK (RAG): Optional.

      See GenAI Retrieve Task for more details.

  7. Click Submit.
Your new tool configuration appears in the list of available tools configurations. You can reference this tool by its tool configuration name in agentic planner tasks and in agent profiles for agentic task and conversational agent.

Parent topic: Manage Internal Tool Configurations