Skip to content
ArtificialFlow

SDKs

Node.js, .NET, and Java cover the HTTP API, workers, and user tasks. Python and Go only activate jobs. With IAM off, leave the token empty. With IAM on, the machine identity needs artificialflowclient.

ClientScopeInstall
Node.jsFull API, workers, user tasksnpm install @artificialflow/nodejs-sdk
.NET 8Full API, workers, user tasksdotnet add package ArtificialFlow.Sdk
Java 17Full API, workers, user tasksio.artificialflow:artificialflow-sdk:1.2.0
Python 3.10+Workers onlypip install -e clients/python-sdk
GoWorkers onlybackend/libs/worker

The recommended gateway root is http://localhost:9100/api/v1. Node.js defaults to that. .NET and Java default to http://localhost:9100/api, and /api/v1 works there too. Unversioned /api remains a compatibility alias. Guides in the repository: Node.js, .NET, Java, Python, and Go.

Node.js

Package @artificialflow/nodejs-sdk at 1.2.0, Node.js 20 or newer. It is a thin client over the same HTTP contract as the other full SDKs.

npm install @artificialflow/nodejs-sdk
import { ArtificialFlowClient } from "@artificialflow/nodejs-sdk"

const client = new ArtificialFlowClient({
  baseUrl: "http://localhost:9100/api/v1",
  token: process.env.ARTIFICIALFLOW_TOKEN,
})

const workflows = await client.listWorkflows({ page: 1, pageSize: 100 })

With IAM_DEPLOYMENT_MODE=false, omit token. With true, pass a token or client-credentials settings (OIDC_TOKEN_URL, OIDC_CLIENT_ID, OIDC_CLIENT_SECRET). The smoke test deploys nothing until you point it at a job type:

cd clients/nodejs-sdk && npm ci && npm run build
ARTIFICIALFLOW_BASE_URL=http://localhost:9100/api \
ARTIFICIALFLOW_WORKER_JOB_TYPE=golden-validate \
node examples/sdk-smoke-test.js

.NET

ArtificialFlow.Sdk targets net8.0 and has no third-party runtime dependencies. Method names follow the OpenAPI operationId with an Async suffix. Configure either a static token or OAuth client credentials, not both. With IAM off, configure neither.

dotnet add package ArtificialFlow.Sdk
using ArtificialFlow.Sdk;

using var client = new ArtificialFlowClient("http://localhost:9100/api");
var workflows = await client.listWorkflowsAsync(new ListWorkflowsOptions { Page = 1, PageSize = 100 });

From a checkout, make sdk-dotnet builds and tests the solution. clients/dotnet-sdk/examples/SdkSmokeTest.cs and WorkerExample.cs are the samples.

Java

io.artificialflow:artificialflow-sdk:1.2.0 needs Java 17. It mirrors the Node.js operations. With IAM off, construct the client with no credentials.

<dependency>
  <groupId>io.artificialflow</groupId>
  <artifactId>artificialflow-sdk</artifactId>
  <version>1.2.0</version>
</dependency>
ArtificialFlowClient client = new ArtificialFlowClient(new ArtificialFlowClientOptions()
    .baseUrl("http://localhost:9100/api"));

Your application signs its own users in, then searches tasks with candidateUser and candidateGroups and claims them with that person as assignee. From a checkout, make sdk-java runs mvn verify.

Python worker

artificialflow-worker (import artificialflow_worker) polls one job type. It is not on PyPI. Install it from the clone. It does not refresh tokens. With IAM on, pass a raw access token. With IAM off, pass "".

pip install -e clients/python-sdk
import os
from artificialflow_worker import Worker

Worker(
    base_url="http://localhost:9100/api",
    token=os.getenv("ARTIFICIALFLOW_TOKEN", ""),
    job_type="golden-validate",
    worker_name="python-worker-1",
    handler=lambda job: {"validated": True},
).run()

The handler receives a dict and returns variables. Raise to fail the job. Jobs do not carry process variables; read them with GET /instances/{id} if you need them. The worker does not extend locks. Keep the handler shorter than the lock, or use Go or a full SDK.

Go worker

Import github.com/artificialflow/artificialflow/backend/libs/worker. It covers /jobs/* and can renew a lock while the handler runs. It does not fetch tokens. Leave BearerToken empty when IAM is off.

client, err := worker.NewClient(worker.ClientConfig{
    BaseURL:     "http://localhost:9100/api",
    BearerToken: os.Getenv("ARTIFICIALFLOW_TOKEN"),
})
w, err := worker.NewWorker(client, worker.WorkerConfig{
    JobType:    "golden-validate",
    WorkerName: "go-worker-1",
    Handler: func(ctx context.Context, job model.Job) (map[string]any, error) {
        return map[string]any{"validated": true}, nil
    },
})
err = w.RunOnce(ctx)

The sample binary is examples/go-worker. Run loops until the context is cancelled. Deploys, instances, and user tasks stay on the HTTP API or a full SDK. The worker protocol is on Workers.