Building AI Agents with Named Queries

Install VS Code Extension

1. Open VS Code or Cursor
2. Navigate to the Extensions marketplace
3. Search for Sema4.ai Data Access
4. Click Install

The extension provides specialized tools for developing named queries, including SQL validation, connection management, and testing capabilities.

Create a New Data Action Project

1. Create a new folder for your data action project
2. Open the folder in VS Code or Cursor
3. Open the Command Palette (Ctrl+Shift+P or Cmd+Shift+P)
4. Type "Create Action Package" and select Sema4.ai: Create Action Package

   

5. Choose your project location (current folder)
6. Name your project (e.g., "my-data-actions")
7. Select the Data Access/Query template

   

   This creates a template project with everything needed for data actions development, including:

• data_actions.py - Contains your named queries with @query decorators
• data_sources.py - Defines data sources for your action package
• SQL script files for development and testing

Connect Data Sources

Before creating queries, you'll need to connect to your data sources:

1. In the Data Access extension, locate the Data Server section
2. Click the "+" button next to the Data Server name
   • Alternatively, open the Command Palette (Cmd+Shift+P or Ctrl+Shift+P) and type Sema4.ai: Add New Data Source

3. Select your data source type:
   • For databases: Choose PostgreSQL, Snowflake, MySQL, etc.
   • For files: Choose File Upload
   • For applications: Choose Salesforce, Slack, etc.
4. Enter the required connection details:
   • For databases: Server, database name, username, password, etc.
   • For files: Browse to select your CSV, JSON, or Excel file
   • For applications: API credentials and authentication details
5. Test the connection to ensure it works properly
6. Give your data source a descriptive name and save it

Once connected, the data source will appear in the Data Explorer. You can browse its schema, tables, and columns to better understand the available data.

Write and Test SQL Queries

Before creating named queries, you can develop and test SQL in the provided .sql files:

1. Open the scratchpad.sql file in your project
2. Write your SQL query against your connected data sources
3. Run the query using one of these methods:
   • Click "Run SQL on Data Server" above your query
   • Use Ctrl+Enter shortcut
   • Use the Command Palette and type "Run Selected SQL"

For example, you might write:

SELECT 
    customer_name, 
    COUNT(order_id) as order_count,
    SUM(order_total) as total_spent
FROM sales_data
WHERE 
    order_date BETWEEN '2023-01-01' AND '2023-12-31'
    AND region = 'Northeast'
GROUP BY customer_name
ORDER BY total_spent DESC
LIMIT 10;

Create a Named Query

Once your SQL is working, convert it to a named query:

1. In your SQL file, position your cursor within the query
2. Click Create Named Query from the context menu (or use Command Palette)

   

3. Name your query (e.g., get_top_customers)
4. Identify parameters in your query (highlighted in yellow)
5. Name and describe each parameter
6. Save the query

This automatically:

• Creates a new @query function in data_actions.py
• Adds any new data sources to data_sources.py
• Creates a test JSON file in the devdata folder

Your named query will look something like this:

@query
def get_top_customers(
    start_date: str,
    end_date: str,
    region: str,
    datasource: Annotated[DataSource, FileSalesDataSource]
) -> Response[Table]:
    """Get top customers by total spending for a specific region and time period.
    
    Args:
        start_date (str): Start date in YYYY-MM-DD format
        end_date (str): End date in YYYY-MM-DD format
        region (str): Sales region to filter by
        
    Returns:
        Table: Top customers with order count and total spent
    """
    ...

Test Your Named Query

To test your named query:

1. In VS Code, find your query in the Sema4.ai SDK extension's Activity panel

   

2. Click the play button next to the query
3. If prompted, select which test input to use
4. Review the results in the console

The test uses the input values defined in the JSON file in the devdata folder. You can modify these values to test different scenarios.

Publish to Studio

Once your named queries are ready:

1. Open the Command Palette
2. Type Publish Action Package and select Sema4.ai: Publish Action Package to Sema4.ai Studio
3. Follow the prompts to complete the publication

Alternatively, to share with others:

1. Use the Sema4.ai: Build Action Package (zip) command
2. Share the resulting ZIP file

Implement in Your Agent

To use your named queries in an agent:

1. Open Studio and navigate to your agent
2. Add the Data Access action package to your agent
3. Update your agent's runbook to utilize the named queries
4. Test your agent with various data-related questions