Agent type and method name mapping

The agents defined by code are compiled to WebAssembly and there are some specific rules of how the agent methods can be referred to from outside the source code, such as from Rib scripts or the CLI.

Component name

The component name must always be in the form of namespace:name. This is enforced when the component is created.

Agent types

The agent types have names idiomatic to the used programming language (for example SampleAgent in TypeScript). However, when referring to them in agent IDs, invocations, etc., we always use the name converted to kebab-case (for example sample-agent).

Agent IDs

Every agent is identified by a unique ID which consists of the agent type (in kebab-case) and its constructor arguments. The constructor arguments are specified in a specific text format in these IDs.

• For regular data types, the WAVE encoding is used, same as in Rib scripts. See the Type Mapping page for more details.
• Unstructured text parameters are either inlined between ", or a remote URL (not in quotes). The inline string can be optionally prefixed with a language code in square brackets.
• Unstructured binary parameters are either base64 encoded between " and prefixed with a mimetype in square brackets, or a remote URL (not in quotes)
• Multimodal values are specified as a list of values, where each value is prefixed with the multimodal type name.

See the following examples of valid agent IDs:

Singleton agent with no parameters

agent-1()

Agent with one numeric parameter

agent-2(12)

Agent with multiple parameters

agent-3(12,{x: 1, y: 2, properties: {a, c}})

Agent with two unstructured text parameters

agent-4(https://url1.com/,https://url2.com/) // tuple with two unstructured text params pointing to a remote URL
agent-4("hello, world!",[en]"\"hello,\" world!") // tuple with two unstructured inline text params, second having a language code prefix

Agent with two unstructured binary parameters

agent-5(https://url1.com/,https://url2.com/) // tuple with two unstructured binary params pointing to a remote URL
agent-5([application/json]"SGVsbG8gd29ybGQh",[image/png]"SGVsbG8gd29ybGQh") // tuple with two unstructured inline binary params with MIME type prefixes

Agent with multimodal parameters

agent-6(z([application/json]"SGVsbG8gd29ybGQh"),x(101)) // multimodal with two values, one named `z` which is a binary and one named `x` which is a wit value

Method names

Agent method names are also converted to kebab-case.

Method names in Rib scripts

When calling methods from Rib, first we get an instance of the agent using the constructor syntax:

let agent1 = sample-agent(1, 2, 3);

Then each exported agent method can be called using the dot syntax, using the kebab-cased method name:

agent1.the-first-method();

Method calls from the CLI or the REST APIs

When directly calling agent methods using golem agent invoke or the REST API, the method name must be constructed to point to the WebAssembly export. This indirection is going to be removed in the future.

The rule to construct the method name is:

namespace:name/agent-type.{method-name}

Here namespace:name is the component name, agent-type is the agent type name in kebab-case, and method-name is the method name in kebab-case.