Functions

Author the functions a new worker contributes to an iii system.

What “writing a function” means

A worker contributes capabilities to a iii system by registering functions. Each function has an id of the form service::name, a handler that receives the payload and returns a result, and optional JSON Schemas that describe the request and response shape.

For how callers invoke functions (worker.trigger / iii trigger / event-bound triggers), see Using iii / Triggers. This page is about the authoring new functions.

Register a function

Inside the worker, register the function with the SDK. The id is what triggers will use as a function_id.

Each type of trigger has its own expected argument structure for a given function. For example cron will call functions without arguments, while http will provide a standard http-style payload that includes body, headers, and other properties. For each worker visit their respective page at workers.iii.dev for their expected payload.

Node / TypeScript

import { registerWorker } from "iii-sdk";

const url = process.env.III_URL;
if (!url) throw new Error("III_URL must be set");
const worker = registerWorker(url);

worker.registerFunction("math::add", async (payload: { a: number; b: number }) => {
  return { c: payload.a + payload.b };
});

Python

import os
from iii import register_worker, InitOptions

worker = register_worker(
    os.environ.get("III_URL"),
    InitOptions(worker_name="math-worker"),
)

def add_handler(payload: dict) -> dict:
    return {"c": payload["a"] + payload["b"]}

worker.register_function("math::add", add_handler)

Rust

use iii_sdk::{InitOptions, RegisterFunction, register_worker};

let url = std::env::var("III_URL").expect("III_URL must be set");
let worker = register_worker(&url, InitOptions::default());

worker.register_function(RegisterFunction::new("math::add", |input: AddInput| {
    Ok(serde_json::json!({ "c": input.a + input.b }))
}));

Attach request and response schemas

Attach JSON Schemas to the registration so the request and response shape are documented alongside the function. The schemas are stored with the function and surface in the iii console and the agent-readable skills.

Runtime validation is not yet supported. Attached schemas are metadata only; the engine does not enforce a specific schema, reject payloads, nor handler return values that don’t match the schemas. Treat the schemas as contract documentation for function invocations, agents, and the console.

Node / TypeScript

import { registerWorker } from "iii-sdk";

const url = process.env.III_URL;
if (!url) throw new Error("III_URL must be set");
const worker = registerWorker(url);

worker.registerFunction(
  "math::add",
  async (payload) => ({ c: payload.a + payload.b }),
  {
    request_format: {
      type: "object",
      properties: { a: { type: "number" }, b: { type: "number" } },
      required: ["a", "b"],
    },
    response_format: {
      type: "object",
      properties: { c: { type: "number" } },
      required: ["c"],
    },
  },
);

Python

import os
from iii import register_worker, InitOptions

worker = register_worker(
    os.environ.get("III_URL"),
    InitOptions(worker_name="math-worker"),
)

worker.register_function(
    "math::add",
    add_handler,
    request_format={
        "type": "object",
        "properties": {"a": {"type": "number"}, "b": {"type": "number"}},
        "required": ["a", "b"],
    },
    response_format={
        "type": "object",
        "properties": {"c": {"type": "number"}},
        "required": ["c"],
    },
)

Rust

use iii_sdk::{InitOptions, RegisterFunction, register_worker};
use schemars::JsonSchema;
use serde::Deserialize;

#[derive(Deserialize, JsonSchema)]
struct AddInput { a: f64, b: f64 }

#[derive(serde::Serialize, JsonSchema)]
struct AddOutput { c: f64 }

let url = std::env::var("III_URL").expect("III_URL must be set");
let worker = register_worker(&url, InitOptions::default());

// Rust derives `request_format` and `response_format` from the closure's
// input and output types via `schemars::JsonSchema`. No builder methods
// are needed — annotate your request/response structs and the SDK
// generates the schemas automatically.
worker.register_function(RegisterFunction::new(
    "math::add",
    |input: AddInput| -> Result<AddOutput, String> {
        Ok(AddOutput { c: input.a + input.b })
    },
));

The schemas also feed the iii console and the agent-readable skills.

HTTP-invokable functions

You can also register an external HTTP endpoint as a function. The engine makes the HTTP call whenever the function is invoked, your worker only declares the endpoint.

This is useful for delegating work to your existing API Gateways, webhooks, serverless platforms (Lambda, Azure Functions, Google Cloud Functions), or any third-party API you want to surface as a regular iii function.

The function is then triggerable like any other: worker.trigger, iii trigger, and any bound trigger type (queue, cron, state, http) all work without any other changes.

Example: register an external webhook as `notifications::send`

Node / TypeScript

import { registerWorker } from "iii-sdk";

const url = process.env.III_URL;
if (!url) throw new Error("III_URL must be set");
const worker = registerWorker(url);

worker.registerFunction(
  "notifications::send",
  {
    url: "https://hooks.provider.example.com/notify",
    method: "POST",
    timeout_ms: 5000,
    headers: { "X-Service": "iii-worker" },
    auth: { type: "bearer", token_key: "PROVIDER_API_TOKEN" },
  },
  { description: "POST a notification to the provider webhook" },
);

Python

import os
from iii import HttpInvocationConfig, InitOptions, register_worker
from iii.iii_types import HttpAuthBearer

worker = register_worker(
    os.environ.get("III_URL"),
    InitOptions(worker_name="notifications-worker"),
)

worker.register_function(
    "notifications::send",
    HttpInvocationConfig(
        url="https://hooks.provider.example.com/notify",
        method="POST",
        timeout_ms=5000,
        headers={"X-Service": "iii-worker"},
        auth=HttpAuthBearer(token_key="PROVIDER_API_TOKEN"),
    ),
    description="POST a notification to the provider webhook",
)

Rust

use std::collections::HashMap;
use iii_sdk::{
    HttpAuthConfig, HttpInvocationConfig, HttpMethod, InitOptions,
    RegisterFunctionMessage, register_worker,
};

let url = std::env::var("III_URL").expect("III_URL must be set");
let worker = register_worker(&url, InitOptions::default());

let mut headers = HashMap::new();
headers.insert("X-Service".into(), "iii-worker".into());

worker.register_function((
    RegisterFunctionMessage::with_id("notifications::send".into())
        .with_description("POST a notification to the provider webhook".into()),
    HttpInvocationConfig {
        url: "https://hooks.provider.example.com/notify".into(),
        method: HttpMethod::Post,
        timeout_ms: Some(5000),
        headers,
        auth: Some(HttpAuthConfig::Bearer {
            token_key: "PROVIDER_API_TOKEN".into(),
        }),
    },
));

HttpInvocationConfig fields

While a normal function takes an id and a handler, http invokeable functions take an id and a HttpInvocationConfig.

Field	Type	Default	Description
url	string	(required)	Endpoint the engine calls when the function is invoked.
method	"GET" | "POST" | "PUT" | "PATCH" | "DELETE"	"POST"	HTTP method.
timeout_ms	number	30000	Per-request timeout in milliseconds.
headers	Record<string, string>	{}	Headers added to every invocation.
auth	HttpAuthConfig	(none)	An object with two fields: bearer, hmac, or api_key AND token_key, secret_key, or value_key

Auth fields (token_key, secret_key, value_key) are specified as the names of environment variables, not the secrets themselves. The engine resolves them from its own process environment at registration time, so secrets stay on the engine host and never travel over the SDK WebSocket.

HTTP error handling

The engine sends the invocation payload as the JSON request body and treats any non-2xx response or network error as an invocation failure that propagates back to the caller. HTTP-invoked functions appear in engine::functions::list and are discoverable through the console exactly like in-process handlers.

Return values and errors

A function returns either a value (which the handler is responsible for shaping to match its documented response schema) or an error. Errors raised inside the handler are propagated to the caller as invocation errors with the worker’s stack trace attached: Node forwards error.stack, Python forwards traceback.format_exc(), and Rust forwards the underlying error’s stack trace. The engine doesn’t swallow them. Use this distinction to express expected failures (return a structured error value) versus unexpected ones (throw / raise / return Err).

Unregister a function

registerFunction returns a handle with an unregister() method that removes the function from the engine at runtime. When the worker disconnects, all of its functions are removed automatically and pending invocations error out.

Node / TypeScript

const add = worker.registerFunction("math::add", async (payload) => {
  return { c: payload.a + payload.b };
});

add.unregister();

Python

add = worker.register_function("math::add", add_handler)

add.unregister()

Rust

let add = worker.register_function(RegisterFunction::new("math::add", |input: AddInput| {
    Ok(serde_json::json!({ "c": input.a + input.b }))
}));

add.unregister();