Copilot

Copilot turns a natural-language prompt into a step-by-step plan and runs that plan against a loan. In the dashboard this is Copilot Agent. In the API, an agent is a task group.

Admins write prompts and generate actions. Anyone on the loan can run a task and watch the result.

sequenceDiagram
    participant User as User
    participant API as Areal API
    participant Copilot as Copilot

    rect rgb(191, 223, 255)
        User->>API: Save a prompt on a task
        API->>Copilot: Generate actions
        Copilot-->>API: Plan
        API-->>User: Task with plan
    end

    rect rgb(200, 255, 200)
        User->>API: Run the task on a loan
        API->>Copilot: Execute plan
        Copilot-->>API: Step results
        API-->>User: WebSocket update (COPILOT_TASK_UPDATED)
    end

Asynchronous runs

Running a task or agent returns immediately. Track progress over the WebSocket API, or poll the task until results.status is no longer pending.

See Status Tracking for the Copilot message types.

Concepts

• Agent (task group). A named set of automations for your organization. The API calls this a task group. It can include a starting condition and a post-run action.
• Task. One prompt, the generated plan, and the latest run for the current loan.
• Run. One execution of a task against a loan. Status is pending, success, failed, or n/a.
• Generated actions. The plan Copilot builds from the prompt. The dashboard shows these as numbered steps.
• Best next action. Guidance Copilot returns when a run fails.

Each task is scoped to a loan through session_id. Create a loan first; see Loans.

Dashboard

Open a loan, then Copilot Agent.

• Everyone sees executions for that loan, can run a task, and can open the result (plan, documents used, best next action).
• Admins can switch to admin view to create agents, write prompts, generate actions, and mark tasks active.

Example Usage

Python

List agents and run a task

import requests

BASE_URL = 'http://dev-api.v2.areal.ai/api/v2'
SESSION_ID = 'your-loan-id'

# 0. Login - details in Authentication section

# 1. List Copilot agents (task groups) for this loan
agents = client.get(
    url=f'{BASE_URL}/copilot/task-group/',
    params={'session_id': SESSION_ID},
).json()

for agent in agents['task_groups']:
    print(f"{agent['id']} - {agent['name']} - {agent['status']}")
    task_group_id = agent['id']

# 2. List tasks in an agent
tasks = client.get(
    url=f'{BASE_URL}/copilot/task-group/{task_group_id}/tasks/',
    params={'session_id': SESSION_ID},
).json()

for task in tasks['objects']:
    print(f"{task['id']} - {task['name']} - {task['results']['status']}")
    task_id = task['id']

# 3. Run a task against this loan
run_response = client.post(
    url=f'{BASE_URL}/copilot/task/{task_id}/execute/',
    json={'session_id': SESSION_ID},
    headers={'Content-Type': 'application/json'},
)
print(run_response.json())

C#

List agents and run a task

using System;
using System.Net.Http;
using System.Threading.Tasks;
using System.Text;
using System.Text.Json;
using System.Net;

var baseUrl = "http://dev-api.v2.areal.ai/api/v2";
var sessionId = "your-loan-id";

// 0. Login - details in Authentication section
// See code_samples/auth/c#/login.cs for authentication

var handler = new HttpClientHandler
{
    UseCookies = true,
    CookieContainer = new CookieContainer()
};
var client = new HttpClient(handler);

// 1. List Copilot agents (task groups) for this loan
var agentsUrl = $"{baseUrl}/copilot/task-group/?session_id={sessionId}";
var agentsResponse = await client.GetAsync(agentsUrl);
agentsResponse.EnsureSuccessStatusCode();

var agentsJson = JsonDocument.Parse(await agentsResponse.Content.ReadAsStringAsync());
string? taskGroupId = null;
foreach (var agent in agentsJson.RootElement.GetProperty("task_groups").EnumerateArray())
{
    taskGroupId = agent.GetProperty("id").GetString();
    var name = agent.GetProperty("name").GetString();
    var status = agent.GetProperty("status").GetString();
    Console.WriteLine($"{taskGroupId} - {name} - {status}");
}

// 2. List tasks in an agent
if (taskGroupId is null)
{
    return;
}

var tasksUrl = $"{baseUrl}/copilot/task-group/{taskGroupId}/tasks/?session_id={sessionId}";
var tasksResponse = await client.GetAsync(tasksUrl);
tasksResponse.EnsureSuccessStatusCode();

var tasksJson = JsonDocument.Parse(await tasksResponse.Content.ReadAsStringAsync());
string? taskId = null;
foreach (var task in tasksJson.RootElement.GetProperty("objects").EnumerateArray())
{
    taskId = task.GetProperty("id").GetString();
    var name = task.GetProperty("name").GetString();
    var runStatus = task.GetProperty("results").GetProperty("status").GetString();
    Console.WriteLine($"{taskId} - {name} - {runStatus}");
}

// 3. Run a task against this loan
if (taskId is null)
{
    return;
}

var executeContent = new StringContent(
    JsonSerializer.Serialize(new { session_id = sessionId }),
    Encoding.UTF8,
    "application/json"
);
var executeResponse = await client.PostAsync($"{baseUrl}/copilot/task/{taskId}/execute/", executeContent);
executeResponse.EnsureSuccessStatusCode();
Console.WriteLine(await executeResponse.Content.ReadAsStringAsync());

Java

List agents and run a task

import java.net.HttpURLConnection;
import java.net.URL;
import java.io.OutputStream;
import java.io.BufferedReader;
import java.io.InputStreamReader;
import java.net.CookieManager;
import java.net.CookieHandler;
import java.nio.charset.StandardCharsets;
import org.json.JSONObject;
import org.json.JSONArray;

public class RunCopilotTask {
    public static void main(String[] args) throws Exception {
        String baseUrl = "http://dev-api.v2.areal.ai/api/v2";
        String sessionId = "your-loan-id";

        // 0. Login - details in Authentication section
        // See code_samples/auth/java/login.java for authentication
        CookieManager cookieManager = new CookieManager();
        CookieHandler.setDefault(cookieManager);

        // 1. List Copilot agents (task groups) for this loan
        JSONObject agents = makeAuthenticatedRequest(
            baseUrl + "/copilot/task-group/?session_id=" + sessionId,
            "GET",
            null
        );
        JSONArray agentList = agents.getJSONArray("task_groups");
        String taskGroupId = null;
        for (int i = 0; i < agentList.length(); i++) {
            JSONObject agent = agentList.getJSONObject(i);
            taskGroupId = agent.getString("id");
            System.out.println(taskGroupId + " - " + agent.getString("name") + " - " + agent.getString("status"));
        }

        // 2. List tasks in an agent
        JSONObject tasks = makeAuthenticatedRequest(
            baseUrl + "/copilot/task-group/" + taskGroupId + "/tasks/?session_id=" + sessionId,
            "GET",
            null
        );
        JSONArray taskList = tasks.getJSONArray("objects");
        String taskId = null;
        for (int i = 0; i < taskList.length(); i++) {
            JSONObject task = taskList.getJSONObject(i);
            taskId = task.getString("id");
            String runStatus = task.getJSONObject("results").optString("status", "n/a");
            System.out.println(taskId + " - " + task.getString("name") + " - " + runStatus);
        }

        // 3. Run a task against this loan
        JSONObject executeBody = new JSONObject();
        executeBody.put("session_id", sessionId);
        JSONObject executeResponse = makeAuthenticatedRequest(
            baseUrl + "/copilot/task/" + taskId + "/execute/",
            "POST",
            executeBody.toString()
        );
        System.out.println(executeResponse);
    }

    private static JSONObject makeAuthenticatedRequest(String urlString, String method, String body) throws Exception {
        URL url = new URL(urlString);
        HttpURLConnection connection = (HttpURLConnection) url.openConnection();
        connection.setRequestMethod(method);
        connection.setRequestProperty("Content-Type", "application/json");
        connection.setDoInput(true);

        if (body != null) {
            connection.setDoOutput(true);
            try (OutputStream os = connection.getOutputStream()) {
                byte[] input = body.getBytes(StandardCharsets.UTF_8);
                os.write(input, 0, input.length);
            }
        }

        int responseCode = connection.getResponseCode();
        if (responseCode == HttpURLConnection.HTTP_OK) {
            try (BufferedReader br = new BufferedReader(
                    new InputStreamReader(connection.getInputStream(), StandardCharsets.UTF_8))) {
                StringBuilder response = new StringBuilder();
                String responseLine;
                while ((responseLine = br.readLine()) != null) {
                    response.append(responseLine.trim());
                }
                return new JSONObject(response.toString());
            }
        }

        connection.disconnect();
        return null;
    }
}

To run every active task in an agent, POST /api/v2/copilot/task-group/{task_group_id}/execute/ with { "session_id": "..." }.

For the full Copilot API see Copilot.