Skip to main content

Documentation Index

Fetch the complete documentation index at: https://prismeai-legacy.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

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:
  1. Access external data from APIs, databases, and services
  2. Perform actions in connected systems
  3. Process information using specialized logic
  4. 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 componentsKey aspects:
  • Unique slug identifier
  • Access control and sharing
  • Integration configuration
  • Event visibility and management

Automations

Server-side processes that perform actions and logicKey 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 eventsKey aspects:
  • System and custom events
  • Event publishing and subscription
  • Asynchronous/synchronous operations
  • Event history and monitoring

Apps Marketplace

Pre-built integrations that can be installedKey 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:
1

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
2

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
3

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
4

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
5

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:
1

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)
2

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
3

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
4

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
5

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 endpointsImplementation:
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 databasesImplementation:
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 conditionsImplementation:
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 systemsImplementation:
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
Tools should be optimized for quick execution whenever possible.Recommendations:
  • Request only needed data (e.g., specific fields, limit result counts)
  • Use caching where appropriate for frequently accessed data
  • Implement timeouts to prevent long-running operations
  • Monitor and optimize query performance
  • Consider asynchronous patterns for long-running operations

​
Integration with AI Knowledge

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

Register the Tool

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
2

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
3

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
4

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:
  1. Configure both RAG and tools in AI Knowledge
  2. Provide clear instruction on when to use each capability
  3. Create tools that supplement knowledge gaps
  4. 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