agent-builder

Agent Builder

The agent diagram is not generated from a model, it is parsed directly out of the source you write. Code that compiles but does not match the shapes below still renders as an incomplete or empty agent, and the user cannot then edit it from the low-code side. Follow every rule.

<...> marks a placeholder to substitute from the user's request. Never emit it literally.

Derive identifiers from the agent's purpose in camelCase, and keep the family consistent: <agent>Agent, <agent>Model, <agent>Listener. Service paths are the exception, they are kebab-case, written <agent-name>.

System prompt: always inline

The system prompt MUST be an inline mapping constructor in the ai:Agent construction. A prompt assigned to a separate variable and referenced by name is not read at all, the agent card renders with no role and no instructions.

Both role and instructions MUST use the string backtick template so multi-line text survives a round trip.

Correct:

final ai:Agent <agent>Agent = check new (
    systemPrompt = {
        role: string `<short role name>`,
        instructions: string `<first line of instructions>
<continuation line, starting at column 0>
<continuation line, starting at column 0>`
    }, model = <agent>Model, tools = [<toolName>, <toolName>]
);

Do not indent the continuation lines of instructions to match the surrounding code, the leading whitespace is part of the string and is shown to the user in the prompt editor. Start every continuation line at column 0, as above.

Model provider: declare the concrete type

Every ai component is identified in the diagram by its declared type, so always declare the concrete class. An abstract type renders as an unresolved node.

final ai:Wso2ModelProvider <agent>Model = check ai:getDefaultModelProvider();

ai:Wso2ModelProvider not ai:ModelProvider; ai:Wso2EmbeddingProvider not ai:EmbeddingProvider; ai:InMemoryVectorStore not ai:VectorStore. When the user names a provider (OpenAI, Azure, Anthropic, Ollama, …) declare that provider's own class, same rule.