Quickstart

Get up and running with the Noukai SDK in under 5 minutes.

Installation

pip install noukai-sdk

Authentication

You need a Noukai API key to authenticate. Obtain one from Noukai Console, then set it as an environment variable:

export NOUKAI_API_KEY=nk_yourkey_...

Or pass it directly to the client:

from noukai_sdk import Noukai
 
client = Noukai(api_key="nk_yourkey_...")

This example executes a spelling-grade flow with a single message. The recommended pattern is to set org and project defaults when constructing the client, so you only need to provide the flow slug.

Local development? Set env: "dev" (Python: env="dev") to connect to http://localhost:8080/api/v1 instead of production. See Local development setup below.

from noukai_sdk import Noukai
 
with Noukai(org="acme", project="spelling") as client:
    flow = client.flow("grade-3")
    result = flow.execute(message="The cat sat on the mat.")
    print(result.output)

The flow runs to completion and returns an ExecuteResult with the final output.

Iterate step-by-step

Instead of waiting for the entire flow, iterate over steps as they complete:

from noukai_sdk import Noukai
 
with Noukai(org="acme", project="spelling") as client:
    flow = client.flow("grade-3")
    for step in flow.steps(message="The cat sat on the mat."):
        print(f"{step.step_id}: {step.output}")

Each iteration yields a StepCompleted event with the step ID and its output.

Get a trace

After execution, inspect step-by-step timing and cost. Note that cost_usd / costUsd is a decimal string (e.g. "0.001234") — parse it before formatting as a float.

from noukai_sdk import Noukai
 
with Noukai(org="acme", project="spelling") as client:
    flow = client.flow("grade-3")
    result = flow.execute(message="The cat sat on the mat.")
 
    trace = flow.run(result.execution_id).trace()
    for step in trace.steps:
        cost = float(step.cost_usd) if step.cost_usd else 0.0
        print(f"{step.step_id}: {step.duration_ms}ms, ${cost:.6f}")

Local development setup

If you're running Noukai locally (e.g., on http://localhost:8080), pass env: "dev" when creating the client:

from noukai_sdk import Noukai
 
# Connects to http://localhost:8080/api/v1
client = Noukai(api_key="...", env="dev", org="acme", project="spelling")

Or set the NOUKAI_ENV environment variable:

export NOUKAI_ENV=dev

Next steps

Streaming execution: See Step-by-step iteration
Tool calls deep dive: See Tool calls
Execution tracing: See Tracing & debugging
Error handling: See Errors & retries

Using Python? You can also use the sync API without async/await. See Async vs Sync.