Build with AlfaWorkplans

Create your first workplan

Learn how to create, monitor, and manage your Alfa workplans using our API.

Alfa workplans are reusable analysis plans that define what analysis to perform. This guide explains how to create, monitor, and manage workplans. Once created, workplans can be executed multiple times to generate reports with fresh data.

Understanding Workplans vs Reports

  • Workplan: An execution plan based on the user’s prompts to create reports.
  • Report: A single execution of a workplan that generates a report.

A workplan can generate multiple reports. See the schedule and automate workplans guide for more details.

Creating your first workplan

Creating a workplan is simple - you just need to provide a clear prompt that describes what you want the workplan to do.

1import requests
2
3BASE_URL = "https://alfa.boosted.ai/client"
4API_KEY = "YOUR_API_KEY_HERE"
5
6headers = {"x-api-key": API_KEY, "Content-Type": "application/json"}
7
8def create_workplan(prompt, args=None):
9    """Create a new workplan with the specified prompt."""
10    url = f"{BASE_URL}/v2/workplans/create"
11    payload = {"prompt": prompt}
12    
13    response = requests.post(url, headers=headers, json=payload)
14    
15    if response.status_code == 200:
16        data = response.json()
17        workplan_id = data.get("workplan_id")
18        status = data.get("status")
19        print(f"Success! Workplan created with ID: {workplan_id}")
20        print(f"Status: {status}")
21        return workplan_id
22    else:
23        print(f"Error: {response.status_code}, {response.text}")
24        return None
25
26# Create a workplan to analyze Microsoft's stock performance
27workplan_id = create_workplan("What was MSFT's close price on Feb 1, 2023 and how does it compare to recent performance?")

For complex analyses, you can include placeholders like {doc} in your prompt to reference custom documents. See our Custom Documents guide for details.

Example: Creating a workplan for comprehensive price target analysis

1

Define your analysis needs

Determine what specific market data you want to analyze

2

Formulate your prompt

Create a clear prompt that specifies exactly what you need:

1comprehensive_prompt = """
2Show a line graph of Target Price Consensus Mean over the past year for Apple. Then show current
3Target Price Consensus High and Target Price Consensus Low in a table. Finally, in a new section,
4get all news developments for the target company, then get the articles associated with those developments.
5Pass the articles to the text to table tool and extract all the analysts that have given ratings and their
6price targets, using the columns research firm, price target, date, and buy/sell recommendation.
7"""
3

Create the workplan

1# Create price target analysis workplan
2analysis_workplan_id = create_workplan(comprehensive_prompt)
3
4print(f"Your price target analysis workplan is being created with ID: {analysis_workplan_id}")

Monitoring workplan creation

After creating a workplan, it goes through a processing phase to build the execution plan. You can check its status to know when it’s ready.

1import time
2
3def get_workplan_status(workplan_id):
4    """Check if a workplan has completed its creation and is ready."""
5    url = f"{BASE_URL}/v2/workplans/{workplan_id}/view"
6    
7    response = requests.get(url, headers=headers)
8    
9    if response.status_code == 200:
10        data = response.json()
11        plan_status = data.get("plan_status")
12        run_status = data.get("run_status")
13        print(f"Plan status: {plan_status}, Run status: {run_status}")
14        return plan_status, run_status
15    else:
16        print(f"Error: {response.status_code}, {response.text}")
17        return None, None
18
19# Poll until the workplan is ready
20plan_status = ""
21while plan_status != "READY":
22    plan_status, run_status = get_workplan_status(workplan_id)
23    if plan_status == "READY":
24        print("Workplan is ready!")
25        break
26    elif plan_status == "FAILED":
27        print("Workplan creation failed")
28        break
29    else:
30        print("Workplan is still being created...")
31        time.sleep(10)

The workplan can be in one of the following states during creation:

  • CREATING: The workplan is being created and processed
  • READY: The workplan is ready to be executed
  • FAILED: The workplan creation failed
  • CANCELLED: The workplan creation was cancelled

Once a workplan has its status set as READY, you can view the execution plan created from the user prompt.

1def get_workplan_details(workplan_id):
2    """Get detailed information about a workplan."""
3    url = f"{BASE_URL}/v2/workplans/{workplan_id}/view"
4    
5    response = requests.get(url, headers=headers)
6    
7    if response.status_code == 200:
8        data = response.json()
9        
10        print(f"Workplan ID: {data.get('workplan_id')}")
11        print(f"Plan Status: {data.get('plan_status')}")
12        print(f"Run Status: {data.get('run_status')}")
13        
14        execution_plan = data.get("execution_plan")
15        if execution_plan:
16            nodes = execution_plan.get("nodes", [])
17            print(f"Execution Plan: {len(nodes)} nodes")
18            
19            for i, node in enumerate(nodes):
20                tool_name = node.get("tool_name", "Unknown")
21                description = node.get("description", "No description")
22                print(f"  Node {i+1}: {tool_name} - {description}")
23        
24        return data
25    else:
26        print(f"Error: {response.status_code}, {response.text}")
27        return None
28
29# Get details for a specific workplan
30workplan_info = get_workplan_details(workplan_id)

Next steps

Now that you know how to create and manage workplans, you can:

For production systems, always implement proper error handling and consider using exponential backoff for status polling to avoid rate limiting.