Use the SDK

Use the AI Studio SDK to work with workspace-scoped Product resources in Go or Python applications. After completing this page, you will use a personal access token to list visible workspaces and obtain the workspace ID required for later tasks.

For all scenarios and task guides, see AI Studio SDK.

Prerequisites: Get the SDK

Before starting, go to Download AI Studio SDK to obtain the offline distribution package for your language (Python wheel or Go source module), then install and verify dependencies locally.

1. Configure the service address and personal access token

Create a personal access token in Credentials, then configure it together with the AI Studio API service address as environment variables:

export PRODUCT_API_BASE_URL='https://api.moi.matrixorigin.cn/v5'
export PRODUCT_API_KEY='<your-personal-access-token>'

Use the address above for the public service. For a private deployment, enter the complete AI Studio API service address supplied by the deployment provider, including its actual API path prefix. The SDK does not append /v5 or /newmoi automatically.

Pass the personal access token as its original value; the SDK sends it in the X-API-Key header. Do not add a Bearer prefix or use a Genesis API endpoint. The following examples read the configuration from environment variables and pass it explicitly to the client.

2. List visible workspaces

AI Studio SDK features must be used in a workspace. Before using workflows, knowledge bases, data, agents, or other features, select the target workspace and get its workspace ID.

List the workspaces accessible to the current identity:

import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
result = client.workspaces().list()
for workspace in result.workspaces:
    print(workspace.id, workspace.name)

package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	result, err := client.Workspaces().List(ctx)
	if err != nil {
		panic(err)
	}
	for _, workspace := range result.GetWorkspaces() {
		fmt.Printf("%s\t%s\n", workspace.GetId(), workspace.GetName())
	}
}

Select a target workspace ID from the output, or copy a workspace ID in the console. Save that ID as an environment variable:

export WORKSPACE_ID='<workspace-id>'

3. Call example

This example calls the List workflows feature. Use the connection details and workspace ID from the previous steps to create a workspace client and list the workflows that the current identity can read:

import os

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
workspace = client.workspace(os.environ["WORKSPACE_ID"])
result = workspace.workflows().list()

print(result.total)
for workflow in result.workflows:
    print(workflow.id, workflow.name, workflow.status)

package main

import (
	"context"
	"fmt"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		panic(err)
	}
	workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		panic(err)
	}
	result, err := workspace.Workflows().List(ctx)
	if err != nil {
		panic(err)
	}

	fmt.Println(result.GetTotal())
	for _, workflow := range result.GetWorkflows() {
		fmt.Printf("%s\t%s\t%s\n", workflow.GetId(), workflow.GetName(), workflow.GetStatus())
	}
}

On success, the program prints the workflow total followed by each workflow’s ID, name, and status.

Symptom

What to check

You receive 401

Check that the personal access token is complete and has no Bearer prefix.

You receive 404 or HTML content

For the public service, check that the address is https://api.moi.matrixorigin.cn/v5. For a private deployment, check that the address includes the actual API path prefix supplied by the deployment provider.

The workspace list is empty or you receive 403

Check that the current account has the required workspace member or role permissions.

Next steps

Last updated on