WIT API Reference

Package

package act:core@0.2.0;

Types

metadata

type metadata = list<tuple<string, list<u8>>>;

Key-value pairs where keys are strings and values are CBOR-encoded bytes.

localized-string

variant localized-string {
    plain(string),
    localized(list<tuple<string, string>>),
}

Use plain("text") for single-language components. Use localized with BCP 47 language tags for multi-language support.

tool-definition

record tool-definition {
    name: string,
    description: option<localized-string>,
    input-schema: option<string>,
    annotations: option<list<tuple<string, list<u8>>>>,
    extensions: option<list<tuple<string, list<u8>>>>,
}

tool-call

record tool-call {
    name: string,
    arguments: option<list<u8>>,
    metadata: metadata,
    extensions: option<list<tuple<string, list<u8>>>>,
}

Arguments are CBOR-encoded (RFC 8949), not JSON strings.

stream-event

variant stream-event {
    content(content-part),
    error(tool-error),
    metadata(list<tuple<string, list<u8>>>),
}

content-part

record content-part {
    mime-type: option<string>,
    data: option<list<u8>>,
    annotations: option<list<tuple<string, list<u8>>>>,
    extensions: option<list<tuple<string, list<u8>>>>,
}

Data encoding depends on mime-type:

• text/* — UTF-8 encoded string
• application/cbor — CBOR value
• absent — opaque bytes

tool-error

record tool-error {
    kind: error-kind,
    message: option<localized-string>,
    extensions: option<list<tuple<string, list<u8>>>>,
}

error-kind

variant error-kind {
    not-found,
    invalid-args,
    timeout,
    capability-denied,
    internal,
    other(string),
}

Transport adapters map these to protocol-specific codes (e.g., not-found → HTTP 404).

Interface: tool-provider

interface tool-provider {
    get-metadata-schema: async func(metadata: metadata)
        -> option<string>;

    list-tools: async func(metadata: metadata)
        -> result<list-tools-response, tool-error>;

    call-tool: async func(call: tool-call)
        -> stream<stream-event>;
}

get-metadata-schema

Returns a JSON Schema object describing the metadata keys the component accepts. Returns none if the component doesn’t require any metadata.

For bridge components, call iteratively — pass partial metadata to discover additional required keys (e.g., a bridge needs a URL before it can describe the remote component’s schema).

list-tools

Returns all available tool definitions. May vary depending on metadata (e.g., a bridge returns different tools depending on the connected service).

call-tool

Executes a tool. Always returns a stream, even for simple results (single content event + stream close).

World

world act-world {
    export tool-provider;
}

Component info is stored in the act:component WASM custom section (CBOR), not exported as a function.

Well-Known Constants

See ACT-CONSTANTS.md for the full registry of std: keys.

Key	Context	Purpose
std:skill	component-info metadata	Agent instructions (markdown)
std:forward	tool-call metadata	Bridge forwarding blob
std:api-key	metadata	API key for remote services
std:bearer-token	metadata	Bearer auth token
std:read-only	tool annotations	Tool does not modify state
std:destructive	tool annotations	Tool may destroy data
std:idempotent	tool annotations	Safe to retry
std:traceparent	metadata	W3C Trace Context
std:request-id	metadata	Correlation ID