UrslyDevelopersBack to experienceExperience

Ursly SDK · 4 maintained · any language by prompt

Your language.
One prompt.

Pick a language and hand the prompt to your coding agent. It installs, verifies and wires the SDK, then shows you a live 200.

Liveawait client.capabilities()GET /api/v1/capabilities

Waiting for the first live response.

// The response payload appears here.

Node 22+ · browsersPackage status unknown

Download, verify, install and call it once.

Add the Ursly TypeScript SDK to this project.
1. Read https://ursly.io/downloads/manifest.json and find the "sdk-typescript" file (an npm .tgz package). If none is listed, stop and tell me the TypeScript package is not published yet. Current public package names began with 0.2.0; if the release is older, stop and explain that its archived manual predates these source examples.
2. Download it from https://ursly.io followed by its path. Compute its SHA-256; if it differs from the manifest, delete the file and stop.
3. Install that local file with this project's package manager (for npm: npm install ./<file>.tgz) so the exact version is recorded in the lockfile.
4. Create a client with base URL https://ursly.io, call await client.capabilities() and show me the 200 response.
Keep the defaults: no automatic retries, no redirects, no logging of request bodies, and never send health or personal data.
Paste it into your coding agent. That is the whole install.

What every SDK does

Input in. Intent out. You decide.

  1. InputA transcript or gesture your app already has
  2. ResolveYour rules, matched by the API
  3. 200Intents in the payload. Nothing executed
  4. Your handlerOnly actions you registered run
Under the hoodFor your agent, not for you.

Runnable source examples and operational details for developers and coding agents.

These examples target the current SDK source. Compare the published archive and its own manual before installation: earlier releases can have different package names and catalog support. The handlers below only print; each example resolves once, then dispatches that same response without another HTTP request. Save TypeScript as an ES module, Python as a script, Go as main.go and Rust as src/main.rs in a project with the matching SDK installed.

SDK integration guide ↓ · Limits and errors

TypeScript

import { UrslyClient, type ResolveRequest } from "@ursly/sdk";

const client = new UrslyClient({ baseUrl: "https://ursly.io" });
client.registerHandler("navigation.open", (action) => {
  console.log(action); // Replace this print-only handler with your application action.
});
const request: ResolveRequest = {
  "input": {
    "confidence": null,
    "sense": "voice",
    "transcript": "open home"
  },
  "rules": [
    {
      "action": {
        "target": "/",
        "type": "navigation.open"
      },
      "enabled": true,
      "id": "home",
      "match": "open home",
      "minConfidence": null
    }
  ]
};
const resolution = await client.resolve(request); // Returns intents, executes nothing.
const executed = await client.dispatch(resolution); // No second HTTP request.
console.log(executed.resolution.status, executed.results.length);

TypeScript manual ↓

Python

import json
from ursly import UrslyClient, ResolveRequest

client = UrslyClient(base_url="https://ursly.io")
client.register_handler(
    "navigation.open", lambda action, intent: print(action)
)
# JSON decoding preserves booleans, nulls and escaped text from the request.
request: ResolveRequest = json.loads("{\"input\":{\"confidence\":null,\"sense\":\"voice\",\"transcript\":\"open home\"},\"rules\":[{\"action\":{\"target\":\"/\",\"type\":\"navigation.open\"},\"enabled\":true,\"id\":\"home\",\"match\":\"open home\",\"minConfidence\":null}]}")
resolution = client.resolve(request)  # Returns intents, executes nothing.
executed = client.dispatch(resolution)  # No second HTTP request.
print(executed["resolution"]["status"], len(executed["results"]))

Python manual ↓

Go

package main

import (
    "context"
    "encoding/json"
    "fmt"
    "os"
)
import ursly "ursly.io/sdk/go"

func run() error {
    ctx := context.Background()
    client, err := ursly.New("https://ursly.io")
    if err != nil {
        return err
    }
    client.RegisterHandler(ursly.ActionNavigationOpen,
        func(ctx context.Context, action ursly.Action, intent ursly.Intent) (any, error) {
            fmt.Println(action) // Replace this print-only handler with your application action.
            return nil, nil
        })
    var req ursly.ResolveRequest
    if err := json.Unmarshal([]byte("{\"input\":{\"confidence\":null,\"sense\":\"voice\",\"transcript\":\"open home\"},\"rules\":[{\"action\":{\"target\":\"/\",\"type\":\"navigation.open\"},\"enabled\":true,\"id\":\"home\",\"match\":\"open home\",\"minConfidence\":null}]}"), &req); err != nil {
        return err
    }
    resolution, err := client.Resolve(ctx, req) // Returns intents, executes nothing.
    if err != nil {
        return err
    }
    executed, err := client.Dispatch(ctx, resolution) // No second HTTP request.
    if err != nil {
        return err
    }
    fmt.Println(executed.Resolution.Status, len(executed.Results))
    return nil
}

func main() {
    if err := run(); err != nil {
        fmt.Fprintln(os.Stderr, err)
        os.Exit(1)
    }
}

Go manual ↓

Rust

use ursly::{Action, ActionRule, ActionType, Client, ResolveRequest, SenseInput, Value};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let client = Client::new("https://ursly.io")?;
    client.register_handler(ActionType::NavigationOpen, |action, _intent| {
        println!("{:?}", action); // Replace this print-only handler with your application action.
        Ok(Value::Null)
    });
    let request = ResolveRequest::new(
        SenseInput::Voice { transcript: "open home".into(), confidence: Some(None) },
        vec![
        ActionRule {
            id: "home".into(), r#match: "open home".into(),
            action: Action::NavigationOpen { target: "/".into() },
            enabled: Some(true),
            min_confidence: Some(None),
        }
        ],
    );
    let resolution = client.resolve(&request)?; // Returns intents, executes nothing.
    let executed = client.dispatch(&resolution)?; // No second HTTP request.
    println!("{:?} {}", executed.resolution.status, executed.results.len());
    Ok(())
}

Rust manual ↓

Every SDK distinguishes API rejection (HTTP status and server code), timeout, cancellation, transport or invalid response, missing handler and handler failure. Responses are validated before any handler runs. The SDK schedules no retries, bundled adapters refuse redirects, and only registered application handlers execute actions. Custom transports must preserve these policies; the integration guide describes transport and cancellation differences.