Quickstart¶
Important: Ensure you have access to AI Refinery and your API key generated before proceeding. Visit this page to learn more about generating your API key.
Note: To better understand the platform, the Core Concepts page provides an architectural overview of AI Refinery’s architecture along with definitions of its key concepts.
Welcome to our Quickstart Guide! This guide is for developers, data scientists, and technical practitioners who want to get started with the AI Refinery SDK quickly. For more details on project setup, see our Project Guidelines.
In this quick start guide, we will provide:
- Installation: How to set up the AI Refinery SDK.
- Example Project: A simple project using both a custom and a built-in utility agent.
SDK Installation Steps¶
⚠️ Note: For Windows, use WSL (Windows Subsystem for Linux) with Ubuntu 22.04 or above.
Follow this guide to install WSL. All other required packages will be installed while installing the SDK.
Prerequisites¶
- Python 3.12 or higher
- pip (Python package installer)
Below are the steps to create a virtual environment, activate the virtual environment, install the SDK package, and deactivate the virtual environment. These steps are crucial in order to ensure a clean, isolated environment for your project, avoid dependency conflicts, and simplify package management.
1. Create a Virtual Environment¶
Windows (WSL) or Linux¶
Open Command Prompt/PowerShell/Terminal and run the following commands to create a new virtual environment with a name of your choice.
MacOS¶
Open Terminal and run the following command:
2. Activate the Virtual Environment¶
In Command Prompt/PowerShell/Terminal, run the following command to activate the virtual environment:
3. Install the SDK Package¶
Install it by executing the following command in your terminal:
4. Deactivating the Virtual Environment¶
When you are done working in the virtual environment, you can deactivate it by running:
You can now start using the AI Refinery™ SDK to build AI systems.Feel free to copy and paste this content into your README.md
file.
Your First Project¶
With the AI Refinery SDK and your API key ready (API key generation guide), you can create your first project. A project is the core building block of AI Refinery, giving you access to multi-agent workflows, and all other features offered by airefinery.
This section shows you how to set up and run a basic project using custom and built-in utility agents, giving you hands-on experience with AI Refinery.
Configuring Credentials with a .env File¶
To facilitate seamless login to the AI Refinery service, begin by creating a .env
file in your project directory and adding the following lines:
Using a
.env
file is a best practice as it keeps credentials secure, avoids accidental exposure in code repositories, and simplifies configuration management across environments.
Make sure to replace your_api_key
with the actual API key you generated. The .env
file will be used to load the API key into your application.
Creating a Custom Agent¶
A custom agent is a Python function designed to process a string query and return a single output. An example of a custom utility agent can be seen below. For more details, please refer to the Custom Agent page.
import asyncio
import os
from air import AsyncAIRefinery, DistillerClient
from dotenv import load_dotenv
load_dotenv() # loads your API_KEY from your local '.env' file
api_key=str(os.getenv("API_KEY"))
async def simple_agent(query: str):
"""
A simple custom agent that generates synthetic data
using Chat Completions API
"""
prompt = f"""Your task is to generate some synthetic data so that it will be useful to answer the user question. Do not mention this is synthetic data in your answer.\n\n{query}"""
client = AsyncAIRefinery(api_key=api_key)
response = await client.chat.completions.create(
messages=[{"role": "user", "content": prompt}],
model="meta-llama/Llama-3.1-70B-Instruct",
)
return response.choices[0].message.content
In this example, the simple_agent
generates synthetic data in response to a user's query using the Chat Completions API. Depending on your requirements, you can customize the agent to be simpler (e.g., returning "hello" for every input query) or more complex (e.g., interacting with other agents or retrieving relevant information using RAG). You can achieve this by modifying the provided function accordingly.
Creating Your Project¶
Next, use our DistillerClient
API to create a distiller client. This client will interface with the AI Refinery service to run your project. Below is a function that sets up the distiller client. Here's what it does:
- Instantiates a
DistillerClient
. - Creates a project named
example
using the configuration specified in theexample.yaml
file. Details ofexample.yaml
are provided in the next section. - Adds the previously defined
simple_agent
to theexecutor_dict
under the nameData Scientist Agent
. - Sends a query to AI Refinery service to be processed, and then prints the recieved response.
async def quickstart_demo():
distiller_client = DistillerClient(api_key=api_key)
# Validate your configuration file before creating the project
is_config_valid = distiller_client.validate_config(config_path="example.yaml")
if not is_config_valid:
# Abort if validation fails to avoid creating an invalid project
print("Configuration validation failed!")
return
# upload your config file to register a new distiller project
distiller_client.create_project(config_path="example.yaml", project="example")
# Define a mapping between your custom agent to Callable.
# When the custom agent is summoned by the super agent / orchestrator,
# distiller-sdk will run the custom agent and send its response back to the
# multi-agent system.
executor_dict = {
"Data Scientist Agent": simple_agent,
}
# connect to the created project
async with distiller_client(
project="example",
uuid="test_user",
executor_dict=executor_dict
) as dc:
responses = await dc.query(query="Who won the FIFA world cup 2022?") # send a query to project
async for response in responses:
print(response['content'])
if __name__ == "__main__":
asyncio.run(quickstart_demo())
⚠️ Note:
project
name &uuid
must conform to our naming conventions.
Project Configuration¶
Next, you will need to configure your project by using YAML.
orchestrator:
agent_list:
# List of agents available in the orchestrator. Each agent must be configure under utility_agents below.
- agent_name: "Data Scientist Agent"
- agent_name: "Search Agent"
utility_agents:
- agent_class: CustomAgent
agent_name: "Data Scientist Agent"
agent_description: "An agent for generating synthetic data." # Description of the Data Scientist Agent
config: {} # Configuration details for the Data Scientist Agent
- agent_class: SearchAgent
agent_name: "Search Agent"
# Configuration and description for Search Agent can be added here
Data Scientist Agent
from the executor_dict
and a built-in utility agent named Search Agent.
The settings for each of these utility agents are specified under utility_agents.
You have the flexibility to expand your project based on your requirements. You can add additional custom agents that you define in the future or integrate built-in agents from our agent library.
Project Setup & Execution¶
Now that you have all the necessary code needed for the project, let us set it up and execute it.
Structure¶
- Create a directory named
example
. - Inside the
example
directory, create a Python file namedexample.py
and place all the Python code mentioned above into this file. - Also, within the
example
directory, create a YAML file namedexample.yaml
and paste the provided YAML configuration into this file. - Additionally, create a
.env
file within theexample
directory and add your environment variables as specified earlier.
This gives us the following project structure:
Execution¶
To execute the example project, run the following commands on your terminal:
Running these commands will create the project on the AI Refinery server. You can now interact with the agents directly from your terminal.