Skip to main content

Property Dialog

Integration starts with a Property Dialog​

Custom Integrations in ai12z are managed through two dialogs: the Property Dialog and the Edit Dialog. The Property Dialog defines the core attributes, behavior, and UX controls that appear in the Edit Dialog.

This dialog allows you to configure key properties such as the integration's name, purpose, data retrieval method, response handling strategy, and optional post-processing logic—ensuring seamless connectivity with your data sources and optimal user experience.

Integration property dialog showing fields for Name, Description, Data Source, Handle Response, and Custom Function.

Fields and Descriptions​

1. Name​

  • Purpose: Assign a unique, descriptive identifier to your integration.
  • Guidance: Choose a name that clearly conveys the integration’s function, making it easily identifiable to both team members and the Reasoning Engine (LLM).

2. Description​

  • Purpose: Provide a concise explanation of the integration’s purpose and functionality (limit: 1000 characters).
  • Guidance: Highlight the primary role of the integration and the type of data or operations it supports. A clear description helps the LLM understand when and how to invoke it.

3. Data Source​

  • Purpose: Define how the integration retrieves its data.

  • Options:

    • None: No external data is fetched. Ideal for template-based integrations such as widgets or calculators.
    • GraphQL: Retrieves data from a GraphQL API.
    • REST API: Retrieves data from a RESTful API.
    • Model Context Protocol (MCP): Retrieves data via an MCP API.

  • Guidance: Match the data source type to the integration’s needs. Choose "None" for static widgets, and "REST" or "GraphQL" for dynamic, real-time integrations.

4. Handle Response​

  • Purpose: Specify how the returned JSON is handled and presented.

  • Options:

    • LLM to process data (default): Sends JSON back to the Reasoning Engine for interpretation and response generation.
    • Carousel: Sends JSON directly to the client for visual display in a list or card format.
    • Template (HTML): Injects the JSON and LLM-generated data into a custom HTML widget (e.g., Google Chart).
    • Form: Dynamically generates an input form using ai12z’s form controls.

  • Process Override (Optional): The integration’s endpoint can override the selected response handler using a process key in the response:

    • carousel: display directly to the user.
    • llm: send to LLM for contextual handling.
    • both: combine visual output and LLM-generated commentary.

    Examples:

    • If a ticketing system returns one result: use both for carousel + LLM context.
    • If zero results: use llm to generate a helpful message.
    • If many results: use carousel to display data directly and skip LLM processing.

  • Guidance: Select the response mode that best fits the intended UX. Use LLM for natural language summaries, Carousel or HTML for rich visuals, or Forms for user input.

5. Custom Function (Python)​

  • Purpose: Optionally apply a Python script for final post-processing of JSON or GraphQL responses before rendering or sending to the LLM.
  • Guidance: Use this when you need more control than what JSONata or filters provide. Python is useful for complex transformations, especially with REST data. For GraphQL, filtering typically happens at the query level, making Python unnecessary in most cases.

6. Generate Description​

  • Purpose: Automatically generate a description for the integration using AI analysis (available after the agent is created).
  • Guidance: The description helps the ReAct LLM understand the integration’s purpose and when to invoke it. A good description improves the relevance and accuracy of AI responses.

After Completing​

Click Next to continue to the Edit Integration Dialog, where you can configure runtime details and connect your integration to its underlying API.

Best Practices​

  • Be Descriptive Yet Concise: Use clear and purposeful names and descriptions. These are essential for discoverability and LLM effectiveness.

  • Choose the Right Data Source: Align your selection with the underlying service architecture. REST and GraphQL are ideal for real-time integrations.

  • Design for the End-User Experience: Select a response handling method (LLM, Carousel, Template, Form) based on how the user will consume the data.

  • Use Custom Functions Wisely: When advanced logic is needed (e.g., field mapping, filtering), leverage Python to transform data before it's rendered or passed to the AI.

Conclusion​

The Edit Property Dialog provides the foundation for customizing how integrations function and present results in the ai12z platform. By thoughtfully configuring these settings, you enable seamless data access, intelligent AI-driven behavior, and a polished, effective user experience.