Module workflow.internal
ballerina/workflow.internal Ballerina library
Functions
registerConnection
Registers a module-level final client object so that it can be passed as
an argument to activity functions whose parameter type is a client object.
This is an internal function used by the compiler plugin. It is emitted
by the source modifier for every module-level final variable whose type is a
client object and is invoked during module initialization, before
startWorkflowRuntime.
When an activity is called with such a client as one of its arguments, the
native runtime substitutes the value with the marker string
"connection:<name>" for transport, then resolves it back to the registered
client on the activity worker side using the same name.
Parameters
- name string - The Ballerina variable name of the client (used as the lookup key)
- connection object {} - The client object reference to register
registerDurableAgentActivity
function registerDurableAgentActivity(string agentName, string toolName, function() () activity, json meta, map<anydata|object {}>? bindings) returns boolean|errorRegisters an activity capability declaration of a durable agent.
Parameters
- agentName string - The agent's name
- toolName string - The tool name advertised to the model
- activity
function() ()- The@workflow:Activityfunction
- meta json (default ()) - Declaration metadata (description, gating, retry policy)
- bindings map<anydata|object {}>? (default ()) - Arguments fixed at registration, keyed by parameter name; client objects are passed by reference to their module-level variable
registerDurableAgentDecl
function registerDurableAgentDecl(string agentName, ModelProvider model, json systemPrompt, int maxIter, typedesc<json>? inputType, typedesc<anydata>? resultType, json eventTimeout, int maxEventWaits) returns boolean|errorRegisters a durable agent declaration: identity, model, system prompt, and reasoning limit. Must be called before the capability registrations below.
Parameters
- agentName string - The agent's name (its module-level variable name)
- model ModelProvider - The agent's
ai:ModelProvider
- systemPrompt json - The agent's system prompt (
role+instructions)
- maxIter int - Per-turn reasoning iteration cap
- inputType typedesc<json>? (default json) - The type of the structured JSON payload accepted alongside the
query:
jsonfor any payload, a narrower type to validate its shape, or()for a query-only agent
- resultType typedesc<anydata>? (default ()) - The agent's declared result type, or
()for the final text response
- eventTimeout json (default ()) - Maximum wait per event wait, or
()to wait indefinitely
- maxEventWaits int (default 50) - Cap on event waits per run
registerDurableAgentEvent
function registerDurableAgentEvent(string agentName, string eventName, typedesc<anydata> request, typedesc<anydata>? response, string cardinality) returns boolean|errorRegisters an event channel declaration of a durable agent.
Parameters
- agentName string - The agent's name
- eventName string - The channel name
- request typedesc<anydata> - The channel's request type
- response typedesc<anydata>? (default ()) - The channel's response type;
()for one-way channels
- cardinality string (default "MULTI_EVENT") -
"MULTI_EVENT"(default) or"SINGLE_EVENT"
registerDurableAgentHumanTask
function registerDurableAgentHumanTask(string agentName, string taskName, json meta, typedesc<anydata> resultType, typedesc<map<json>>? taskInputType) returns boolean|errorRegisters a human task capability declaration of a durable agent.
Parameters
- agentName string - The agent's name
- taskName string - The task name
- meta json (default ()) - Declaration metadata (roles, title, description)
- resultType typedesc<anydata> (default anydata) - Expected result type; drives form schema generation
- taskInputType typedesc<map<json>>? (default ()) - Declared input shape; the agent-supplied input is checked against it. Nil keeps the open default
registerDurableAgentPeer
function registerDurableAgentPeer(string agentName, string peerName, string targetAgent, json meta) returns boolean|errorRegisters a peer-agent declaration of an object-model durable agent: the peer is advertised to the agent's model as a delegable tool and runs as a true Temporal child workflow of the agent.
registerDurableAgentRunner
Registers the shared object-model runner as an agent's workflow: the agent gets
its own workflow type (workflow-<agentName>) whose activities are the agent's
declared activity functions plus the built-in agent activities. The runner and
the built-ins are captured natively at workflow-module init, so callers pass
only the agent name — no runner machinery leaks into any public API.
Parameters
- agentName string - The agent's name (its module-level variable name)
registerDurableAgentTool
function registerDurableAgentTool(string agentName, BaseToolKit|ToolConfig|FunctionTool tool, anydata approvalPolicy) returns boolean|errorRegisters an AI tool of an object-model durable agent: stored on the declaration
(so the runner can advertise it to the model) and published to the agent tool
registry (so the built-in executeAgentTool activity can resolve it).
Parameters
- agentName string - The agent's name (its module-level variable name)
- tool BaseToolKit|ToolConfig|FunctionTool - The tool: an
@ai:AgentToolfunction, anai:ToolConfig, or a toolkit
- approvalPolicy anydata (default ()) - The tool's
ApprovalPolicy: a review definition gates every call, nil does not
registerWorkflowDescriptor
Hands the build-time workflow descriptor (workflow.def.json) to the runtime as data.
This is an internal function: the compiler plugin embeds the canonical descriptor
document in the generated __registerWorkflowsAndStart() so the runtime can register
every described workflow, activity, and human task and resolve the implementation
functions by their recorded coordinates when the worker starts. This single data-only
call replaces the former per-workflow registerWorkflow/registerHumanTask codegen.
Parameters
- descriptorJson string - The canonical descriptor document
startWorkflowRuntime
Starts the workflow runtime after all workflows have been registered.
This is an internal function used by the compiler plugin as the last
generated module-level statement, ensuring that polling only begins after
every registerWorkflow call has executed.