Tool Integration

Tool integration connects AI agents to external systems, databases, and services, enabling them to perform actions beyond conversation. This guide explores the options for implementing tools in Prisme.ai and provides practical examples for different integration scenarios.

Understanding Tool Integration

Tools in Prisme.ai represent functional capabilities that agents can use to:

Access external data from APIs, databases, and services
Perform actions in connected systems
Process information using specialized logic
Execute workflows across multiple systems

Effective tool integration requires a clear understanding of both the agent’s needs and the target systems’ capabilities and requirements.

Tool Integration Approaches

Prisme.ai offers multiple approaches to tool integration, each suited to different requirements and technical expertise levels:

Configure tools through AI Knowledge’s graphical interface.

Ideal for:

Business users and subject matter experts
Simple integrations with existing systems
Quick deployment of common tool types
Combining knowledge and tool capabilities

Key capabilities:

Visual tool configuration
Pre-built tool templates
Custom tool definition
Direct integration with RAG agents
Basic error handling

The AI Builder Foundation

AI Builder provides the foundational capabilities for all tool integrations in Prisme.ai, built on these core concepts:

Workspaces

Project environments that organize related components

Key aspects:

Unique slug identifier
Access control and sharing
Integration configuration
Event visibility and management

Automations

Server-side processes that perform actions and logic

Key aspects:

Triggering via events, URLs, or schedules
Sequential or parallel execution
Conditional branching and loops
Variable management
Error handling

Event-Driven Architecture

Communication pattern using asynchronous events

Key aspects:

System and custom events
Event publishing and subscription
Asynchronous/synchronous operations
Event history and monitoring

Apps Marketplace

Pre-built integrations that can be installed

Key aspects:

Ready-to-use connectors
Configuration options
Documentation access
Custom blocks and automations

Creating Tools in AI Knowledge

For business users, AI Knowledge provides a straightforward interface for adding tools to agents:

Access Tool Configuration

Navigate to the Tools section in your AI Knowledge agent.

The Tools section allows you to:

View currently configured tools
Add new tools
Edit existing tool configurations
Test tool functionality

Select Tool Type

Choose from built-in tools or custom integrations.

Available options typically include:

Built-in tools: Web browsing, image generation, code interpreter
Custom tools: API endpoints, AI Builder automations
Third-party tools: Integrations from the marketplace

Configure Tool Parameters

Set up the required parameters and options.

Configuration typically includes:

Tool name and description (used by the LLM for selection)
Required parameters (what the agent needs to provide)
Authentication settings
Output formatting preferences
Usage limits and constraints

Connect to Backend

Link the tool to its execution environment.

This connection can be to:

A built-in service endpoint
An AI Builder automation
An external API endpoint
A marketplace app integration

Test and Validate

Verify the tool functions correctly.

Testing should include:

Verification with sample inputs
Error case testing
Performance assessment
Output format validation

Building Custom Tools in AI Builder

For more advanced requirements, AI Builder provides comprehensive capabilities for creating custom tools:

Create an Automation

Start by creating a new automation in your AI Builder workspace.

Key configuration elements:

Unique slug identifier
Human-readable name
Description (critical for LLM understanding)
Trigger type (endpoint for tools)

Define Input Schema

Create a structured definition of the tool’s parameters.

The schema should include:

Required and optional parameters
Parameter types and constraints
Default values where appropriate
Descriptive field names
Validation rules

Implement Logic

Build the workflow that executes when the tool is called.

Implementation options include:

Visual workflow with built-in actions
Native YAML workflows event driven or Custom code (Python/Node.js)
Conditional branching and loops
Error handling and retries
Integration with external systems

Format Response

Define how results are returned to the agent.

Response formatting considerations:

Structured data for easy LLM processing
Clear labeling of results
Error information when needed
Context for result interpretation
Performance metrics if relevant

Test and Debug

Validate the tool functions correctly in isolation.

Testing approaches include:

Manual execution with sample inputs
Monitoring in the Activity view
Error case simulation
Performance testing
Integration testing with agents

Example: Web Browsing Tool Implementation

Let’s examine the implementation of a Web Browsing tool:

The tool is defined with clear parameters and description:

slug: Web-browsing
name: AIK/Tools/Web browsing
description: Return list of web browsing results.
when:
  endpoint: true
output:
  type: tool_result
  output: '{{output}}'
labels:
  - tools

This definition includes:

A unique identifier (slug)
A descriptive name for organization
A clear description for LLM understanding
The trigger type (endpoint)
Output format specification
Categorizing labels

The parameter schema defines what the agent needs to provide:

validateArguments: true
arguments:
  body:
    type: object
    properties:
      arguments:
        type: object
        properties:
          type:
            type: string
            enum:
              - search
              - news
              - images
              - videos
              - places
              - reviews
              - scholar
              - patents
              - shopping
          query:
            type: string
            title: User query
          country:
            type: string
            title: Country
          lg:
            type: string
            title: lg
          location:
            type: string
            title: location
          tbs:
            title: Date range
            type: string
            enum:
              - ''
              - qdr:h
              - qdr:d
              - qdr:w
              - qdr:m
              - qdr:y
            enumNames:
              - Any time
              - Past hours
              - Past 24 hours
              - Past week
              - Past month
              - Past year

This schema:

Defines the required structure of input data
Sets constraints on parameter values (e.g., enums)
Provides descriptive titles for parameters
Includes options for different search types
Specifies format validation requirements

The tool’s execution logic handles authentication, processing, and error cases:

do:
  - conditions:
      '{{body.projectId}} != {{config.agentCredentials.projectId}} || !{{run.sourceWorkspaceId}} || {{run.sourceWorkspaceId}} != {{global.workspacesRegistry[''ai-knowledge''].id}}':
        - set:
            name: output
            value:
              error: Forbidden
        - break: {}
  - Serper.run:
      type: '{{body.arguments.type}}'
      q: '{{body.arguments.query}}'
      ql: '{{body.arguments.country}}'
      location: '{{body.arguments.location}}'
      num: 20
      output: search
      hl: '{{body.arguments.lg}}'
      tbs: '{{body.arguments.tbs}}'
  - set:
      name: currentDate
      value: '{% date({{run.date}}).iso %}'
  - set:
      name: output
      value:
        value: '{{search}}'
        description: List of search results

This implementation:

Validates permissions and authentication
Handles security constraints
Calls an external service (Serper)
Processes the results
Formats the output for the agent

Common Tool Integration Patterns

API Integration

Connect to RESTful services and endpoints

Implementation:

do:
  - fetch:
      url: https://api.example.com/data
      method: GET
      headers:
        Authorization: Bearer {{config.apiKey}}
      output: apiResponse
  - set:
      name: output
      value:
        value: '{{apiResponse.body}}'
        description: Data retrieved from API

This pattern is useful for integrating with external services that provide RESTful APIs.

Database Query

Retrieve information from databases

Implementation:

do:
  - DB.query:
      connection: '{{config.dbConnection}}'
      query: 'SELECT * FROM products WHERE category = {{body.arguments.category}}'
      output: queryResults
  - set:
      name: output
      value:
        value: '{{queryResults}}'
        description: Product data from database

This pattern enables agents to access structured data stored in databases.

Conditional Processing

Handle different scenarios based on conditions

Implementation:

do:
  - conditions:
      '{{body.arguments.type}} == "detailed"':
        - set:
            name: fields
            value: "id,name,description,price,specifications,reviews"
      '{{body.arguments.type}} == "summary"':
        - set:
            name: fields
            value: "id,name,price"
  - fetch:
      url: https://api.example.com/products/{{body.arguments.productId}}
      method: GET
      query:
        fields: '{{fields}}'
      output: productData
  - set:
      name: output
      value:
        value: '{{productData.body}}'
        description: Product information

This pattern allows different processing paths based on input parameters or other conditions.

Multi-System Orchestration

Coordinate actions across multiple systems

Implementation:

do:
  - CRM.getCustomer:
      customerId: '{{body.arguments.customerId}}'
      output: customer
  - Inventory.checkAvailability:
      productId: '{{body.arguments.productId}}'
      output: availability
  - conditions:
      '{{availability.inStock}}':
        - Orders.createOrder:
            customerId: '{{customer.id}}'
            productId: '{{body.arguments.productId}}'
            quantity: '{{body.arguments.quantity}}'
            output: orderResult
        - set:
            name: output
            value:
              value: '{{orderResult}}'
              description: Order created successfully
      default:
        - set:
            name: output
            value:
              value:
                error: 'Product not available'
                estimatedRestock: '{{availability.estimatedRestock}}'
              description: Product availability information

This pattern enables complex workflows that span multiple systems and include conditional logic.

Best Practices for Tool Integration

The tool description is critical for the LLM to understand when and how to use the tool.

Good Example:

description: Search the web for current information based on a user query. Returns a list of search results including titles, snippets, and URLs. Best used for finding recent information not available in internal knowledge bases.

Poor Example:

description: Web search tool

The good example clearly explains:

What the tool does
What it returns
When it should be used

This helps the agent make appropriate decisions about tool selection and use.

Parameter schemas should be clear, descriptive, and properly constrained.

Good Example:

properties:
  query:
    type: string
    title: Search query
    description: The specific information to search for on the web
  resultCount:
    type: integer
    title: Number of results
    description: How many search results to return
    minimum: 1
    maximum: 20
    default: 5

Poor Example:

properties:
  q:
    type: string
  n:
    type: integer

The good example includes:

Descriptive titles and descriptions
Clear constraints (min/max)
Default values where appropriate
Self-documenting parameter names

Tools should handle errors gracefully and provide useful information for recovery.

Good Example:

do:
  - try:
      do:
        - fetch:
            url: https://api.example.com/data
            method: GET
            output: apiResponse
      catch:
        - conditions:
            '{{error.statusCode}} == 401':
              - set:
                  name: output
                  value:
                    error: 'Authentication failed. Please check API credentials.'
            '{{error.statusCode}} == 404':
              - set:
                  name: output
                  value:
                    error: 'Requested resource not found. Please verify parameters.'
            default:
              - set:
                  name: output
                  value:
                    error: 'An error occurred: {{error.message}}'

This approach:

Handles specific error cases differently
Provides clear, actionable error messages
Includes context about what went wrong
Enables the agent to respond appropriately

Secure handling of credentials and authentication is essential.

Good Example:

do:
  - fetch:
      url: https://api.example.com/data
      method: GET
      headers:
        Authorization: Bearer {{config.apiKey}}
      output: apiResponse

Key practices:

Store sensitive credentials in configuration, not hardcoded
Use appropriate authentication mechanisms for each service
Handle token expiration and refresh when needed
Implement proper error handling for authentication failures

Integration with AI Knowledge

Once you’ve created tools in AI Builder, you can make them available to agents in AI Knowledge:

Make your automation available as a tool.

This typically involves:

Adding appropriate labels (e.g., ‘tools’)
Ensuring the automation has an endpoint trigger
Verifying the description is LLM-friendly
Checking the parameter schema is complete

Configure in AI Knowledge

Add the tool to your AI Knowledge agent.

In AI Knowledge:

Navigate to the Tools section
Select “Add Custom Tool”
Choose your AI Builder automation
Configure any additional settings

Create Usage Instructions

Add specific guidance for when and how to use the tool.

Effective instructions include:

Clear criteria for when to use the tool
Guidance on parameter formatting
Examples of successful usage
Error handling recommendations

Test in Context

Verify the tool works properly within the agent context.

Testing should include:

Typical usage scenarios
Edge cases and error conditions
Performance under load
Integration with other agent capabilities

Monitoring and Debugging Tool Execution

AI Builder’s Activity view provides comprehensive visibility into tool execution:

This view allows you to:

See all events in chronological order
Filter by event type, status, or date range
View detailed execution information
Diagnose errors and performance issues
Track tool usage patterns

The Activity view is invaluable for debugging tool issues, as it shows the complete execution flow including parameter values, intermediate states, and error conditions.

Security Considerations

When integrating tools, consider these security best practices:

Authentication Management

Store credentials securely in configuration
Use appropriate auth mechanisms (OAuth, API keys, etc.)
Implement proper token management
Follow the principle of least privilege

Access Control

Limit tool access to appropriate users
Validate permissions before execution
Implement proper tenant isolation
Audit tool usage regularly

Data Handling

Minimize sensitive data exposure
Implement proper data sanitization
Follow data retention policies
Handle PII according to regulations

Input Validation

Validate all parameters before use
Implement strict schema validation
Protect against injection attacks
Handle unexpected inputs gracefully

Advanced Integration Techniques

For complex workflows, implement multi-step orchestration patterns.

Example:

do:
  - set:
      name: workflowState
      value:
        status: 'initiated'
        step: 1
        data: {}
  - emit:
      event: workflow.started
      data:
        workflowId: '{{run.id}}'
  - DB.query:
      query: 'SELECT * FROM customers WHERE id = {{body.arguments.customerId}}'
      output: customer
  - set:
      name: workflowState.data.customer
      value: '{{customer}}'
  - set:
      name: workflowState.step
      value: 2
  - emit:
      event: workflow.customer.loaded
      data:
        workflowId: '{{run.id}}'
        customer: '{{customer}}'
  # Continue with additional steps...

This approach:

Maintains workflow state throughout execution
Emits events at key points for monitoring
Breaks complex processes into manageable steps
Creates an audit trail of actions

Combine knowledge retrieval with tool execution for powerful capabilities.

Implementation Strategy:

Configure both RAG and tools in AI Knowledge
Provide clear instruction on when to use each capability
Create tools that supplement knowledge gaps
Implement tools that can act on retrieved information

Example Instruction:

First check our internal knowledge base for product information. If you find basic details but pricing is missing or outdated, use the ProductPricing tool to retrieve current pricing. If the product isn't found in our knowledge base, use the ProductLookup tool to search our catalog API.

Implement logic to choose appropriate tools based on context.

Example:

do:
  - conditions:
      '{{body.arguments.dataSource}} == "internal"':
        - InternalDB.query:
            query: '{{body.arguments.query}}'
            output: results
      '{{body.arguments.dataSource}} == "partner"':
        - PartnerAPI.fetch:
            endpoint: /data
            query: '{{body.arguments.query}}'
            output: results
      '{{body.arguments.dataSource}} == "public"':
        - PublicData.search:
            query: '{{body.arguments.query}}'
            output: results
      default:
        - InternalDB.query:
            query: '{{body.arguments.query}}'
            output: internalResults
        - conditions:
            '{{internalResults.length}} > 0':
              - set:
                  name: results
                  value: '{{internalResults}}'
            default:
              - PublicData.search:
                  query: '{{body.arguments.query}}'
                  output: results
  - set:
      name: output
      value:
        value: '{{results}}'
        description: 'Query results'

This pattern:

Allows explicit source selection
Implements fallback strategies
Optimizes data access paths
Provides consistent result formatting

Next Steps

Ready to implement tool integration for your agents? Continue your journey with these resources:

Tool Selection

Learn how to implement effective tool selection logic

Memory Management

Understand state management across tool interactions

Execution & Activity

Master monitoring and debugging tool execution

Error Handling

Implement robust error management for tools

Getting Started

Prompting & RAG Agent

Tool-Using Agents

Understanding Tool Integration

Tool Integration Approaches

The AI Builder Foundation

Workspaces

Automations

Event-Driven Architecture

Apps Marketplace

Creating Tools in AI Knowledge

Building Custom Tools in AI Builder

Example: Web Browsing Tool Implementation

Common Tool Integration Patterns

API Integration

Database Query

Conditional Processing

Multi-System Orchestration

Best Practices for Tool Integration

Integration with AI Knowledge

Monitoring and Debugging Tool Execution

Security Considerations

Authentication Management

Access Control

Data Handling

Input Validation

Advanced Integration Techniques

Next Steps

Tool Selection

Memory Management

Execution & Activity

Error Handling

Getting Started

Prompting & RAG Agent

Tool-Using Agents

​Understanding Tool Integration

​Tool Integration Approaches

​The AI Builder Foundation

Workspaces

Automations

Event-Driven Architecture

Apps Marketplace

​Creating Tools in AI Knowledge

​Building Custom Tools in AI Builder

​Example: Web Browsing Tool Implementation

​Common Tool Integration Patterns

API Integration

Database Query

Conditional Processing

Multi-System Orchestration

​Best Practices for Tool Integration

​Integration with AI Knowledge

​Monitoring and Debugging Tool Execution

​Security Considerations

Authentication Management

Access Control

Data Handling

Input Validation

​Advanced Integration Techniques

​Next Steps

Tool Selection

Memory Management

Execution & Activity

Error Handling

Understanding Tool Integration

Tool Integration Approaches

The AI Builder Foundation

Creating Tools in AI Knowledge

Building Custom Tools in AI Builder

Example: Web Browsing Tool Implementation

Common Tool Integration Patterns

Best Practices for Tool Integration

Integration with AI Knowledge

Monitoring and Debugging Tool Execution

Security Considerations

Advanced Integration Techniques

Next Steps