Module ai

ballerina/ai Ballerina library

1.1.1

Overview

This module offers APIs for developing AI applications and agents powered by Large Language Models (LLMs).

AI agents use LLMs to process natural language inputs, generate responses, and make decisions based on given instructions. These agents can be designed for various tasks, such as answering questions, automating workflows, or interacting with external systems.

Quickstart

To use the ai module in your Ballerina application, update the .bal file as follows:

Step 1: Import the module

Import the ai module.


import ballerina/ai;

Step 2: Define the System Prompt

A system prompt guides the AI's behavior, tone, and response style, defining its role and interaction with users.


ai:SystemPrompt systemPrompt = {
    role: "Math Tutor",
    instructions: string `You are a helpful math tutor. Explain concepts clearly with examples and provide step-by-step solutions.`
};

Step 3: Define the Model Provider

Ballerina currently supports multiple model providers, which you can explore here on Ballerina Central.

In addition to these prebuilt implementations, you also have the flexibility to implement your own custom provider.

Here's how to initialize the prebuilt OpenAI model provider:


import ballerinax/ai.model.provider.openai;

final ai:ModelProvider openAiModel = check new openai:Provider("openAiApiKey", modelType = openai:GPT_4O);

Step 4: Define the tools

An agent tool extends the AI's abilities beyond text-based responses, enabling interaction with external systems or dynamic tasks. Define tools as shown below:


# Returns the sum of two numbers
# + a - first number
# + b - second number
# + return - sum of the numbers
@ai:AgentTool
isolated function sum(int a, int b) returns int => a + b;

@ai:AgentTool
isolated function mult(int a, int b) returns int => a * b;

Constraints for defining tools:

The function must be marked isolated.
Parameters should be a subtype of anydata.
The tool should return a subtype of anydata|http:Response|stream<anydata, error>|error.
Tool documentation enhances LLM performance but is optional.

Step 5: Define the Memory

The ai module manages memory for individual user sessions using the Memory. By default, agents are configured with a memory that has a predefined capacity. To create a stateless agent, set the memory to () when defining the agent. Additionally, you can customize the memory capacity or provide your own memory implementation. Here's how to initialize the default memory with a new capacity:


final ai:Memory memory = new ai:MessageWindowChatMemory(20);

Step 6: Define the Agent

Create a Ballerina AI agent using the configurations created earlier:


final ai:Agent mathTutorAgent = check new (
    systemPrompt = systemPrompt,
    model = openAiModel,
    tools = [sum, mult], // Pass array of function pointers annotated with @ai:AgentTool
    memory = memory
);

Step 7: Invoke the Agent

Finally, invoke the agent by calling the run method:


mathTutorAgent.run("What is 8 + 9 multiplied by 10", sessionId = "student-one");

If using the agent with a single session, you can omit the sessionId parameter.

Examples

The ai module provides practical examples illustrating usage in various scenarios. Explore these examples, covering the following use cases:

Personal AI Assistant - Demonstrates how to implement a personal AI assistant using Ballerina AI module along with Google Calendar and Gmail integrations

Functions

augmentUserQuery

Isolated Function

function augmentUserQuery(QueryMatch[]|Document[] context, string query) returns ChatUserMessage

Augments the user's query with relevant context.

Parameters

context QueryMatch[]|Document[] - Array of matched chunks or documents to include as context

query string - The user's original question

Return Type

ChatUserMessage - The augmented query with injected context

chunkDocumentRecursively

Isolated Function

function chunkDocumentRecursively(Document document, int maxChunkSize, int maxOverlapSize, RecursiveChunkStrategy strategy) returns Chunk[]|Error

Provides functionality to recursively chunk a text document using a configurable strategy.

The chunking process begins with the specified strategy and recursively falls back to finer-grained strategies if the content exceeds the configured maxChunkSize. Overlapping content between chunks can be controlled using maxOverlapSize.

Parameters

document Document - The input document to be chunked

maxChunkSize int (default 200) - Maximum number of characters allowed per chunk

maxOverlapSize int (default 40) - Maximum number of characters to reuse from the end of the previous chunk when creating the next one. This overlap is made of complete sentences taken in reverse from the previous chunk, without exceeding this limit. It helps maintain context between chunks during splitting.

strategy RecursiveChunkStrategy (default PARAGRAPH) - The recursive chunking strategy to use. Defaults to PARAGRAPH

Return Type

Chunk[]|Error - An array of chunks, or an ai:Error if the chunking fails.

executeTool

Isolated Function

function executeTool(FunctionTool tool, map<json> llmToolInput) returns ToolExecutionResult

Executes an AgentTool.

Parameters

tool FunctionTool - Function pointer to the AgentTool

llmToolInput map<json> - Tool input generated by the LLM

Return Type

ToolExecutionResult - Result of the tool execution

extractToolsFromOpenApiJsonSpec

Isolated Function

function extractToolsFromOpenApiJsonSpec(map<json> openApiSpec, *AdditionInfoFlags additionInfoFlags) returns HttpApiSpecification & readonly|Error

Extracts the Http tools from the given OpenAPI specification as a JSON

Parameters

openApiSpec map<json> - A valid OpenAPI specification in JSON format

additionInfoFlags *AdditionInfoFlags - Flags to extract additional information from the OpenAPI specification

Return Type

HttpApiSpecification & readonly|Error - A record with the list of extracted tools and the service URL (if available)

extractToolsFromOpenApiSpecFile

Isolated Function

function extractToolsFromOpenApiSpecFile(string filePath, *AdditionInfoFlags additionInfoFlags) returns HttpApiSpecification & readonly|Error

Extracts the Http tools from the given OpenAPI specification file.

Parameters

filePath string - Path to the OpenAPI specification file (should be JSON or YAML)

additionInfoFlags *AdditionInfoFlags - Flags to extract additional information from the OpenAPI specification

Return Type

HttpApiSpecification & readonly|Error - A record with the list of extracted tools and the service URL (if available)

getDefaultEmbeddingProvider

Isolated Function

function getDefaultEmbeddingProvider() returns Wso2EmbeddingProvider|Error

Creates a default embedding provider based on the provided wso2ProviderConfig.

Return Type

Wso2EmbeddingProvider|Error - A Wso2EmbeddingProvider instance if the configuration is valid; otherwise, an ai:Error.

getDefaultModelProvider

Isolated Function

function getDefaultModelProvider() returns Wso2ModelProvider|Error

Creates a default model provider based on the provided wso2ProviderConfig.

Return Type

Wso2ModelProvider|Error - A Wso2ModelProvider instance if the configuration is valid; otherwise, an ai:Error.

getToolConfigs

Isolated Function

function getToolConfigs(FunctionTool[] tools) returns ToolConfig[]

Generates a array of ToolConfig from the given list of function pointers.

Parameters

tools FunctionTool[] - Array of function pointers annotated with @ai:AgentTool annotation

Return Type

ToolConfig[] - Array of ai:ToolConfig instances

getTools

Isolated Function

function getTools(Agent agent) returns Tool[]

Get the tools registered with the agent.

Parameters

agent Agent - Agent instance

Return Type

Tool[] - Array of tools registered with the agent

parseOpenApiSpec

Isolated Function

function parseOpenApiSpec(map<json> openApiSpec) returns OpenApiSpec|UnsupportedOpenApiVersion|OpenApiParsingError

Parses the given OpenAPI specification as a JSON to a OpenApiSpec object.

Parameters

openApiSpec map<json> - A valid OpenAPI specification in JSON format

Return Type

OpenApiSpec|UnsupportedOpenApiVersion|OpenApiParsingError - A OpenApiSpec object

Classes

ai: Agent

Isolated

Represents an agent.

Constructor

Initialize an Agent.

init (*AgentConfiguration config)

config *AgentConfiguration - Configuration used to initialize an agent

run

Isolated Function

function run(string query, string sessionId) returns string|Error

Executes the agent for a given user query.

Parameters

query string - The natural language input provided to the agent

sessionId string (default DEFAULT_SESSION_ID) - The ID associated with the agent memory

Return Type

string|Error - The agent's response or an error

ai: HttpServiceToolKit

Isolated

Defines a HTTP tool kit. This is a special type of tool kit that can be used to invoke HTTP resources. Require to initialize the toolkit with the service url and http tools that are belongs to a single API.

Constructor

Initializes the toolkit with the given service url and http tools.

init (string serviceUrl, HttpTool[] httpTools, ClientConfiguration clientConfig, map<string|string[]> headers)

serviceUrl string - The url of the service to be called

httpTools HttpTool[] - The http tools to be initialized

clientConfig ClientConfiguration {} - The http client configuration associated to the tools

headers map<string|string[]> {} - The http headers to be used in the requests

getTools

Isolated Function

function getTools() returns ToolConfig[]

Useful to retrieve the Tools extracted from the HttpTools.

Return Type

ToolConfig[] - An array of Tools corresponding to the HttpTools

ai: InMemoryVectorStore

Isolated

An in-memory vector store implementation that provides simple storage for vector entries.

Constructor

Initializes a new in-memory vector store.

init (int topK, SimilarityMetric similarityMetric)

topK int 3 - The maximum number of top similar vectors to return in query results

similarityMetric SimilarityMetric COSINE - The metric used for vector similarity

add

Isolated Function

function add(VectorEntry[] entries) returns Error?

Adds vector entries to the in-memory store. Only supports dense vectors in this implementation. If a vector entry with the same ID already exists, it will be replaced.

Parameters

entries VectorEntry[] - Array of vector entries to store. If an entry does not contain an id, a unique id will be generated by default.

Return Type

Error? - nil on success; an Error if non-dense vectors are provided

query

Isolated Function

function query(VectorStoreQuery query) returns VectorMatch[]|Error

Queries the vector store for vectors similar to the given query.

Parameters

query VectorStoreQuery - The query containing the embedding vector and optional filters

Return Type

VectorMatch[]|Error - An array of vector matches sorted by similarity score (limited to topK), or an ai:Error if the query fails

delete

Isolated Function

function delete(string id) returns Error?

Deletes a vector entry from the in-memory store. Removes the entry that matches the given reference ID.

Parameters

id string - The reference ID of the vector entry to delete

Return Type

Error? - ai:Error if the reference ID is not found, otherwise nil

ai: McpToolKit

Isolated

Represents a toolkit for interacting with an MCP server, invoking tools via the MCP protocol.

callTool

Isolated Function

function callTool(CallToolParams params) returns CallToolResult|error

Parameters

params CallToolParams -

getTools

Isolated Function

function getTools() returns ToolConfig[]

ai: MessageWindowChatMemory

Isolated

Provides an in-memory chat message window with a limit on stored messages.

Constructor

Initializes a new memory window with a default or given size.

init (int size)

size int 10 - The maximum capacity for stored messages

get

Isolated Function

function get(string sessionId) returns ChatMessage[]|MemoryError

Retrieves a copy of all stored messages, with an optional system prompt.

Parameters

sessionId string - The ID associated with the memory

Return Type

ChatMessage[]|MemoryError - A copy of the messages, or an ai:Error

update

Isolated Function

function update(string sessionId, ChatMessage message) returns MemoryError?

Adds a message to the window.

Parameters

sessionId string - The ID associated with the memory

message ChatMessage - The ChatMessage to store or use as system prompt

Return Type

MemoryError? - nil on success, or an ai:Error if the operation fails

delete

Isolated Function

function delete(string sessionId) returns MemoryError?

Removes all messages from the memory.

Parameters

sessionId string - The ID associated with the memory

Return Type

MemoryError? - nil on success, or an ai:Error if the operation fails

ai: ToolStore

Isolated

Constructor

init ((BaseToolKit|ToolConfig|FunctionTool)... tools)

tools (BaseToolKit|ToolConfig|FunctionTool)... - A list of tools that are available to the LLM

execute

Isolated Function

function execute(LlmToolResponse action) returns ToolOutput|LlmInvalidGenerationError|ToolExecutionError

execute the tool decided by the LLM.

Parameters

action LlmToolResponse - Action object that contains the tool name and inputs

Return Type

ToolOutput|LlmInvalidGenerationError|ToolExecutionError - ActionResult containing the results of the tool execution or an error if tool execution fails

Fields

tools map<Tool> & readonly -

ai: VectorKnowledgeBase

Isolated

Represents a vector knowledge base for managing chunk indexing and retrieval operations. The VectorKnowledgeBase handles converting chunks to embeddings, storing them in a vector store, and enabling retrieval through a Retriever.

Constructor

Initializes a new VectorKnowledgeBase instance.

init (VectorStore vectorStore, EmbeddingProvider embeddingModel)

vectorStore VectorStore - The vector store for embedding persistence

embeddingModel EmbeddingProvider - The embedding provider for generating vector representations

ingest

Isolated Function

function ingest(Chunk[] chunks) returns Error?

Indexes a collection of chunks. Converts each chunk to an embedding and stores it in the vector store, making the chunk searchable through the retriever.

Parameters

chunks Chunk[] - The array of chunk to index

Return Type

Error? - An ai:Error if indexing fails; otherwise, nil

retrieve

Isolated Function

function retrieve(string query, MetadataFilters? filters) returns QueryMatch[]|Error

Retrieves relevant chunk for the given query.

Parameters

query string - The text query to search for

filters MetadataFilters? (default ()) - Optional metadata filters to apply during retrieval

Return Type

QueryMatch[]|Error - An array of matching chunks with similarity scores, or an ai:Error if retrieval fails

ai: VectorRetriever

Isolated

Represents a retriever that finds relevant chunks based on query similarity. The Retriever combines query embedding generation and vector search to return matching chunks along with their similarity scores.

Constructor

Initializes a new Retriever instance.

init (VectorStore vectorStore, EmbeddingProvider embeddingModel)

vectorStore VectorStore - The vector store to search in

embeddingModel EmbeddingProvider - The embedding provider to use for generating query embeddings

retrieve

Isolated Function

function retrieve(string query, MetadataFilters? filters) returns QueryMatch[]|Error

Retrieves relevant chunks for the given query.

Parameters

query string - The text query to search for

filters MetadataFilters? (default ()) - Optional metadata filters to apply during retrieval

Return Type

QueryMatch[]|Error - An array of matching chunks with similarity scores, or an ai:Error if retrieval fails

Clients

ai: ChatClient

Isolated

A client class for interacting with a chat service.

Constructor

Initializes the ChatClient with the provided service URL and configuration.

init (string serviceUrl, *ChatClientConfiguration clientConfig)

serviceUrl string - The base URL of the chat service.

clientConfig *ChatClientConfiguration - Configuration options for the chat client.

post chat

Isolated FunctionResource Function

function post chat(ChatReqMessage request) returns ChatRespMessage|error

Handles incoming chat messages by sending a request to the chat service.

Parameters

request ChatReqMessage - The chat request message to be sent.

Return Type

ChatRespMessage|error - A ChatRespMessage containing the response from the chat service, or an error if the request fails.

ai: Wso2EmbeddingProvider

Isolated

WSO2 embedding provider implementation that provides embedding capabilities using WSO2's AI service.

Constructor

Initializes a new Wso2EmbeddingProvider instance.

init (string serviceUrl, string accessToken, *ConnectionConfig connectionConfig)

serviceUrl string - The base URL of WSO2 intelligence API endpoint

accessToken string - The access token for authenticating API requests

connectionConfig *ConnectionConfig - Additional HTTP connection configuration

embed

Isolated FunctionRemote Function

function embed(Chunk chunk) returns Embedding|Error

Converts chunk to embedding.

Parameters

chunk Chunk - The data to embed

Return Type

Embedding|Error - Embedding representation of the chunk content or an ai:Error if the embedding service fails

batchEmbed

Isolated FunctionRemote Function

function batchEmbed(Chunk[] chunks) returns Embedding[]|Error

Converts a batch of chunks into embeddings.

Parameters

chunks Chunk[] - The array of chunks to be converted into embeddings

Return Type

Embedding[]|Error - An array of embeddings on success, or an ai:Error

ai: Wso2ModelProvider

Isolated

WSO2 model provider implementation that provides chat completion capabilities using WSO2's AI services.

Constructor

Initializes a new WSO2ModelProvider instance.

init (string serviceUrl, string accessToken, decimal temperature, *ConnectionConfig connectionConfig)

serviceUrl string - The base URL of WSO2 intelligence API endpoint

accessToken string - The access token for authenticating API requests

temperature decimal DEFAULT_TEMPERATURE - The temperature for controlling randomness in the model's output

connectionConfig *ConnectionConfig - Additional HTTP connection configuration

chat

Isolated FunctionRemote Function

function chat(ChatMessage[]|ChatUserMessage messages, ChatCompletionFunctions[] tools, string? stop) returns ChatAssistantMessage|Error

Sends a chat request to the model with the given messages and tools.

Parameters

messages ChatMessage[]|ChatUserMessage - List of chat messages or a user message

tools ChatCompletionFunctions[] - Tool definitions to be used for the tool call

stop string? (default ()) - Stop sequence to stop the completion

Return Type

ChatAssistantMessage|Error - Function to be called, chat response or an error in-case of failures

generate

Isolated FunctionRemote Function

function generate(Prompt prompt, typedesc<anydata> td) returns td|Error

Sends a chat request to the model and generates a value that belongs to the type corresponding to the type descriptor argument.

Parameters

prompt Prompt - The prompt to use in the chat messages

td typedesc<anydata> (default <>) - Type descriptor specifying the expected return type format

Return Type

td|Error - Generates a value that belongs to the type, or an error if generation fails

Service types

ai: ChatService

Distinct

Defines a chat service interface that handles incoming chat messages.

post chat

Resource Function

function post chat(ChatReqMessage request) returns ChatRespMessage|error

Parameters

request ChatReqMessage -

Enums

ai: AgentType

Represents the different types of agents supported by the module.

Members

REACT_AGENT - Represents a ReAct agent

FUNCTION_CALL_AGENT - Represents a function call agent

ai: EncodingStyle

Members

FORM

SIMPLE

MATRIX

LABEL

SPACEDELIMITED

PIPEDELIMITED

DEEPOBJECT

ai: HeaderStyle

Members

SIMPLE

ai: HttpMethod

Supported HTTP methods.

Members

GET

POST

DELETE

PUT

PATCH

HEAD

OPTIONS

ai: InputType

Supported input types by the Tool schemas.

Members

STRING

INTEGER

FLOAT

BOOLEAN

NUMBER

OBJECT

ARRAY

NULL

ai: MetadataFilterCondition

Represents logical conditions for combining multiple metadata filtering during vector search operations.

Members

AND

ai: MetadataFilterOperator

Represents the set of supported operators used for metadata filtering during vector search operations.

Members

EQUAL

NOT_EQUAL

GREATER_THAN

LESS_THAN

GREATER_THAN_OR_EQUAL

LESS_THAN_OR_EQUAL

NOT_IN

ai: ParameterLocation

Members

QUERY

HEADER

PATH

ai: RecursiveChunkStrategy

Represents the available strategies for recursively chunking a document.

Each strategy attempts to include as much content as possible using a specific unit (such as paragraph or sentence). If the content exceeds the defined maxChunkSize in RecursiveChunker, the strategy recursively falls back to a finer-grained unit until the content fits within the limit.

Members

CHARACTER - Splits text by individual characters.

WORD - Splits text by words. Falls back to CHARACTER if the chunk exceeds the size limit. Word boundaries are detected using at least one space character (" "). Any extra whitespace before or after words, such as multiple spaces or newline characters, is ignored. Examples of valid word separators include " ", " ", "\n", and " \n ". When multiple words fit within the limit, they are joined together using a single space (" ").

LINE - Splits text by lines. Falls back to WORD, then CHARACTER, if the chunk exceeds the size limit. Line boundaries are identified using at least one newline character ("\n"). Any extra whitespace before or after lines is ignored. Examples of valid line separators include "\n", "\n\n", " \n", and "\n ". When multiple lines fit within the limit, they are joined together using a single newline ("\n").

SENTENCE - Splits text by sentences. Falls back to WORD, then CHARACTER, if the chunk exceeds the size limit. Sentence boundaries are detected using OpenNLP's sentence detector (https://opennlp.apache.org). When multiple sentences fit within the limit, they are joined together using a single space (" ").

PARAGRAPH - Splits text by paragraphs. Falls back to SENTENCE, then WORD, then CHARACTER, if the chunk exceeds the size limit. Paragraph boundaries are detected using at least two newline characters ("\n\n"). Any extra whitespace before, between, or after paragraphs is ignored. Examples of valid paragraph separators include "\n\n", "\n\n\n", "\n \n", and " \n \n ". When multiple paragraphs fit within the limit, they are joined together using a double newline ("\n\n").

ai: ROLE

Roles for the chat messages.

Members

SYSTEM

USER

ASSISTANT

FUNCTION

ai: SimilarityMetric

Represents the similarity metrics used for comparing vectors. Defines how the similarity between vectors is calculated during search operations.

Members

COSINE - Cosine similarity measures the cosine of the angle between two vectors

EUCLIDEAN - Euclidean distance calculates the straight-line distance between two points in space

DOT_PRODUCT - Reflect the directional similarity between two vectors

ai: VectorStoreQueryMode

Represents query modes to be used with vector store. Defines different search strategies for retrieving relevant chunks based on the type of embeddings and search algorithms to be used.

Members

DENSE - Uses dense vector embeddings for similarity search

SPARSE - Uses sparse vector embeddings for similarity search

HYBRID - Uses hybrid embeddings that combine dense and sparse representations

Listeners

ai: Listener

A server listener for handling chat service requests.

attach

Isolated Function

function attach(ChatService chatService, string[]|string? name) returns error?

Parameters

chatService ChatService -

name string[]|string? (default ()) -

detach

Isolated Function

function detach(ChatService chatService) returns error?

Parameters

chatService ChatService -

'start

Isolated Function

function 'start() returns error?

gracefulStop

Isolated Function

function gracefulStop() returns error?

immediateStop

Isolated Function

function immediateStop() returns error?

Annotations

ai: AgentTool

ToolAnnotationConfig

function, object function

Represents the annotation of a function tool.

ai: JsonSchema

map<json>

type

Configurables

ai: wso2ProviderConfig

Wso2ProviderConfig?(default ())

Configurable for WSO2 provider.

Records

ai: AdditionInfoFlags

Closed record

Defines additional information to be extracted from the OpenAPI specification.

Fields

extractDescription boolean(default false) - Flag to extract description of parameters and schema attributes from the OpenAPI specification

extractDefault boolean(default false) - Flag to extract default values of parameters and schema attributes from the OpenAPI specification

ai: AgentConfiguration

Closed record

Provides a set of configurations for the agent.

Fields

systemPrompt SystemPrompt - The system prompt assigned to the agent

model ModelProvider - The model used by the agent

tools (BaseToolKit|ToolConfig|FunctionTool)[](default []) - The tools available for the agent

maxIter INFER_TOOL_COUNT|int(default INFER_TOOL_COUNT) - The maximum number of iterations the agent performs to complete the task. By default, it is set to the number of tools + 1.

verbose boolean(default false) - Specifies whether verbose logging is enabled

memory Memory?(default Memory) - The memory used by the agent to store and manage conversation history

ai: AllOfInputSchema

Closed record

Defines an allOf input field in the schema. Follows OpenAPI 3.x specification.

Fields

Fields Included from *BaseInputSchema

description string
default json
nullable boolean

allOf JsonSubSchema[] - List of possible input types

ai: AllOfSchema

All of schema object.

Fields

Fields Included from *BaseSchema

description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

allOf Schema[] - List of schemas that should match

ai: AnyOfInputSchema

Closed record

Defines an anyOf input field in the schema. Follows OpenAPI 3.x specification.

Fields

Fields Included from *BaseInputSchema

description string
default json
nullable boolean

anyOf JsonSubSchema[] - List of possible input types

ai: AnyOfSchema

Any of schema object.

Fields

Fields Included from *BaseSchema

description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

anyOf Schema[] - List of schemas that should match

discriminator? Discriminator - Discriminator

ai: ArrayInputSchema

Closed record

Defines an array input field in the schema.

Fields

Fields Included from *BaseInputTypeSchema

type InputType
description string
default json
nullable boolean

'type ARRAY(default ARRAY) - Input data type. Should be ARRAY.

items JsonSubSchema - Schema of the array items

default? json[] - Default value for the array

ai: ArraySchema

Array schema object.

Fields

Fields Included from *BaseTypeSchema

type string
anyOf never
oneOf never
allOf never
not never
description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

'type ARRAY(default ARRAY) - Type of the array schema

uniqueItems? boolean - Whether the array items are unique

items Schema - Schema of the array items

minItems? int - Minimum number of items in the array

maxItems? int - Maximum number of items in the array

properties? never - Not allowed properties

ai: AudioDocument

Closed record

Represents an audio document.

Fields

Fields Included from *Document

type string
metadata Metadata
content anydata

'typereadonly "audio" (default "audio") - Fixed type identifier for audio documents

content Url|byte[] - Audio content, either a URL or binary data

ai: BaseInputSchema

Closed record

Defines a base input type schema.

Fields

description? string - Description of the input

default? json - Default value of the input

nullable? boolean - Indicates whether the value can be null.

ai: BaseInputTypeSchema

Closed record

Defines a base input schema with type field.

Fields

Fields Included from *BaseInputSchema

description string
default json
nullable boolean

'type InputType - Input data type

ai: BasePrimitiveTypeSchema

Base primitive type schema object.

Fields

Fields Included from *BaseTypeSchema

type string
anyOf never
oneOf never
allOf never
not never
description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

properties? never - Can not have properties in a primitive type schema

items? never - Can not have items in a primitive type schema

ai: BaseSchema

Base schema object.

Fields

description? string - Description of the schema

default? json - Default value of the schema

nullable? boolean - Whether the value is nullable

'xml? XmlSchema - Xml schema

\$ref? never - Not allowed $ref property

ai: BaseTypeSchema

Base type schema object.

Fields

Fields Included from *BaseSchema

description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

'type string - Type of the schema

anyOf? never - Not allowed anyOf

oneOf? never - Not allowed oneOf

allOf? never - Not allowed allOf

not? never - Not allowed not

ai: BooleanSchema

Boolean schema object.

Fields

Fields Included from *BasePrimitiveTypeSchema

properties never
items never
type string
anyOf never
oneOf never
allOf never
not never
description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

'type BOOLEAN - Type of the boolean schema

ai: ChatAssistantMessage

Closed record

Assistant chat message record.

Fields

role ASSISTANT - Role of the message

content string?(default ()) - The contents of the assistant message Required unless tool_calls or function_call is specified

name? string - An optional name for the participant Provides the model information to differentiate between participants of the same role

toolCalls FunctionCall[]?(default ()) - The function calls generated by the model, such as function calls

ai: ChatClientConfiguration

Closed record

Represents the configuration for a chat client.

ai: ChatCompletionFunctions

Closed record

Function definitions for function calling API.

Fields

name string - Name of the function

description string - Description of the function

parameters? map<json> - Parameters of the function

ai: ChatFunctionMessage

Closed record

Function message record.

Fields

role FUNCTION - Role of the message

content string?(default ()) - Content of the message

name string - Name of the function when the message is a function call

id? string - Identifier for the tool call

ai: ChatReqMessage

Closed record

Represents a request message for the chat service.

Fields

sessionId string - A unique identifier for the chat session.

message string - The content of the chat message sent by the user.

ai: ChatRespMessage

Closed record

Represents a response message from the chat service.

Fields

message string - The response message generated by the chat service.

ai: ChatSystemMessage

Closed record

System chat message record.

Fields

role SYSTEM - Role of the message

content string|Prompt - Content of the message

name? string - An optional name for the participant Provides the model information to differentiate between participants of the same role

ai: ChatUserMessage

Closed record

User chat message record.

Fields

role USER - Role of the message

content string|Prompt - Content of the message

name? string - An optional name for the participant Provides the model information to differentiate between participants of the same role

ai: Chunk

Closed record

Represents a chunk of a document.

Fields

Fields Included from *Document

type string
metadata Metadata
content anydata

ai: Components

Map of component objects.

Fields

schemas? map<Schema|Reference> - A map of reusable schemas for different data types

responses? map<Response|Reference> - A map of reusable response objects

parameters? map<Parameter|Reference> - A map of reusable parameter objects

requestBodies? map<RequestBody|Reference> - A map of reusable request body objects

headers? map<Header|Reference> - A map of reusable header objects

pathItems? map<PathItem|Reference> - A map of PathItem objects

ai: ConnectionConfig

Closed record

Configurations for controlling the behaviours when communicating with a remote HTTP endpoint.

Fields

httpVersion HttpVersion(default http:HTTP_2_0) - The HTTP version understood by the client

http1Settings ClientHttp1Settings(default {}) - Configurations related to HTTP/1.x protocol

http2Settings ClientHttp2Settings(default {}) - Configurations related to HTTP/2 protocol

timeout decimal(default 60) - The maximum time to wait (in seconds) for a response before closing the connection

forwarded string(default "disable") - The choice of setting forwarded/x-forwarded header

poolConfig? PoolConfiguration - Configurations associated with request pooling

cache CacheConfig(default {}) - HTTP caching related configurations

compression Compression(default http:COMPRESSION_AUTO) - Specifies the way of handling compression (accept-encoding) header

circuitBreaker? CircuitBreakerConfig - Configurations associated with the behaviour of the Circuit Breaker

retryConfig? RetryConfig - Configurations associated with retrying

responseLimits ResponseLimitConfigs(default {}) - Configurations associated with inbound response size limits

secureSocket? ClientSecureSocket - SSL/TLS-related options

proxy? ProxyConfig - Proxy server related options

validation boolean(default true) - Enables the inbound payload validation functionality which provided by the constraint package. Enabled by default

ai: ConstantValueSchema

Closed record

Defines a constant value field in the schema.

Fields

'const json - The constant value.

ai: Discriminator

Discriminator object.

Fields

propertyName string - Name of the property that specifies the type

mapping? map<string> - Mapping of the property values to schema names

ai: Document

Closed record

Represents the common structure for all document types

Fields

'type string - The type of the document or chunk

metadata? Metadata - Associated metadata

content anydata - The actual content

ai: Encoding

Describes a encoding definition applied to a schema property.

Fields

style? string - Describes how a specific property value will be serialized depending on its type

explode? boolean - When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map

contentType? string - The Content-Type for encoding a specific property

headers? map<Header|Reference> - A map allowing additional information to be provided as headers

ai: ExecutionError

Closed record

Fields

llmResponse json - Response generated by the LLM

'error LlmInvalidGenerationError|ToolExecutionError|MemoryError - Error caused during the execution

observation string - Observation on the caused error as additional instruction to the LLM

ai: ExecutionProgress

Closed record

Execution progress record

Fields

query string - Question to the agent

history ExecutionStep[](default []) - Execution history up to the current action

context map<json>|string?(default ()) - Contextual instruction that can be used by the agent during the execution

ai: ExecutionResult

Closed record

Execution step information

Fields

tool LlmToolResponse - Tool decided by the LLM during the reasoning

observation anydata|error - Observations produced by the tool during the execution

ai: ExecutionStep

Closed record

Execution step information

Fields

llmResponse json - Response generated by the LLM

observation anydata|error - Observations produced by the tool during the execution

ai: FileDocument

Closed record

Represents a generic file document.

Fields

Fields Included from *Document

type string
metadata Metadata
content anydata

'typereadonly "file" (default "file") - Fixed type identifier for file documents

content byte[]|Url|FileId - File content, a URL, binary data, or a file ID reference

ai: FileId

Closed record

Represents an ID referring to a file.

Fields

fileId string - Unique identifier for the file

ai: FunctionCall

Closed record

Function call record

Fields

name string - Name of the function

arguments map<json>?(default {}) - Arguments of the function

id? string - Identifier for the tool call

Describes HTTP headers.

Fields

required? boolean - Whether this header parameter is mandatory

description? string - A brief description of the header parameter

allowEmptyValue? string - Whether empty value is allowed

style? HeaderStyle - Describes how a specific property value will be serialized depending on its type

explode? boolean - When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map

schema? Schema - Schema of the header parameter

content? map<MediaType> - Content of the header parameter

\$ref? never - Not allowed $ref

ai: HttpApiSpecification

Closed record

Provides extracted tools and service URL from the OpenAPI specification.

Fields

serviceUrl? string - Extracted service URL from the OpenAPI specification if there is any

tools HttpTool[] - Extracted Http tools from the OpenAPI specification

ai: HttpOutput

Closed record

Defines an HTTP output record for requests.

Fields

code int - HTTP status code of the response

path string - HTTP path url with encoded paramteres

headers record {| contentType string, contentLength int |} - Response headers

body? json|xml - Response payload

ai: HttpTool

Closed record

Defines an HTTP tool. This is a special type of tool that can be used to invoke HTTP resources.

Fields

name string - Name of the Http resource tool

description string - Description of the Http resource tool used by the LLM

method HttpMethod - Http method type (GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS)

path string - Path of the Http resource

parameters? map<ParameterSchema> - path and query parameters definitions of the Http resource

requestBody? RequestBodySchema - Request body definition of the Http resource

ai: HybridVector

Closed record

Represents a hybrid embedding containing both dense and sparse vector representations.

Fields

dense Vector - Dense vector representation of the embedding

sparse SparseVector - Sparse vector representation of the embedding

ai: ImageDocument

Closed record

Represents an image document.

Fields

Fields Included from *Document

type string
metadata Metadata
content anydata

'typereadonly "image" (default "image") - Fixed type identifier for image documents

content Url|byte[] - Image content, either a URL or binary data

ai: IntegerSchema

Integer schema object.

Fields

Fields Included from *BasePrimitiveTypeSchema

properties never
items never
type string
anyOf never
oneOf never
allOf never
not never
description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

'type INTEGER - Type of the integer schema

format? string - Format of the value

minimum? int - Minimum value of the integer value

maximum? int - Maximum value of the integer value

exclusiveMinimum? boolean - Whether the minimum value is exclusive

exclusiveMaximum? boolean - Whether the maximum value is exclusive

multipleOf? int - Multiplier of the integer value

ai: InternalValueSchema

Closed record

Defines a internal value field in the schema

Fields

Fields Included from *ConstantValueSchema

const json

ai: LlmToolResponse

Closed record

Tool selected by LLM to be performed by the agent

Fields

name string - Name of the tool to selected

arguments map<json>?(default {}) - Input to the tool

id? string - Identifier for the tool call

ai: MediaType

Defines media type of a parameter, response body or header.

Fields

schema Schema(default {}) - Schema of the content

encoding? map<Encoding> - Encoding of the content

ai: Metadata

Represents additional metadata associated with documents or nodes.

Fields

mimeType? string - MIME type specification for the file

fileName? string - File name for the document

fileSize? decimal - File size in bytes

createdAt? Utc - Creation timestamp of the file

modifiedAt? Utc - Modification timestamp of the file

json... - Rest field

ai: MetadataFilter

Closed record

Represents a metadata filter for vector search operations. Defines conditions to filter vectors based on their associated metadata values.

Fields

key string - The name of the metadata field to filter

operator MetadataFilterOperator(default EQUAL) - The comparison operator to use. Defaults to EQUAL

value json - The value to compare the metadata field against

ai: MetadataFilters

Closed record

Represents a container for combining multiple metadata filters using logical operators. Enables complex filtering by applying multiple conditions with AND/OR logic during vector search.

Fields

filters (MetadataFilters|MetadataFilter)[] - An array of MetadataFilter or nested MetadataFilters to apply

condition MetadataFilterCondition(default AND) - The logical operator (AND or OR) used to combine the filters. Defaults to AND

ai: NotInputSchema

Closed record

Defines a not input field in the schema. Follows OpenAPI 3.x specification.

Fields

Fields Included from *BaseInputSchema

description string
default json
nullable boolean

not JsonSubSchema - Schema that is not accepted as an input

ai: NotSchema

Not schema object.

Fields

Fields Included from *BaseSchema

description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

not Schema - Schema that should not match

ai: NumberSchema

Number schema object.

Fields

Fields Included from *BasePrimitiveTypeSchema

properties never
items never
type string
anyOf never
oneOf never
allOf never
not never
description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

'type NUMBER|FLOAT - Type of the number schema

format? string - Format of the value

minimum? int|float - Minimum value of the number value

maximum? int|float - Maximum value of the number value

exclusiveMinimum? boolean - Whether the minimum value is exclusive

exclusiveMaximum? boolean - Whether the maximum value is exclusive

multipleOf? int|float - Multiplier of the number value

ai: ObjectInputSchema

Closed record

Defines an object input field in the schema.

Fields

Fields Included from *BaseInputTypeSchema

type InputType
description string
default json
nullable boolean

'type OBJECT(default OBJECT) - Input data type. Should be OBJECT.

required? string[] - List of required properties

properties? map<JsonSubSchema> - Schema of the object properties

ai: ObjectSchemaType1

Defines an bbject schema with type is specified and properties are optional.

Fields

Fields Included from *BaseTypeSchema

type string
anyOf never
oneOf never
allOf never
not never
description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

'type OBJECT - Type of the object schema

minProperties? int - Minimum number of properties in the object

maxProperties? int - Maximum number of properties in the object

required? boolean|string[] - List of required properties

properties? map<Schema> - List of properties

additionalProperties? boolean|Schema - Additional properties

discriminator? Discriminator - Discriminator

items? never - Not allowed items. Distinction between array and object

ai: ObjectSchemaType2

Defines an object schema with the properties defined and type is unspecified.

Fields

Fields Included from *ObjectSchemaType1

type "object"
minProperties int
maxProperties int
required boolean|string[]
properties map<Schema>
additionalProperties boolean|IntegerSchema|NumberSchema|StringSchema|BooleanSchema|ArraySchema|ObjectSchemaType1|ObjectSchemaType2|OneOfSchema|AllOfSchema|AnyOfSchema|NotSchema|Reference
discriminator Discriminator
items never
anyOf never
oneOf never
allOf never
not never
description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

'type? never - To match when type is not specified, but properties are specified

properties map<Schema> - List of properties

ai: OneOfInputSchema

Closed record

Defines an oneOf input field in the schema. Follows OpenAPI 3.x specification.

Fields

oneOf JsonSubSchema[] - List of possible input types

nullable? boolean - Indicates whether the value can be null.

description? string - Description of the input

ai: OneOfSchema

One of schema object.

Fields

Fields Included from *BaseSchema

description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

oneOf Schema[] - List of schemas that should match

discriminator? Discriminator - Discriminator

ai: OpenApiSpec

OpenAPI Specification 3.1.0

Fields

openapi string - OpenAPI version

servers? Server[] - Server information

paths? Paths - Server resource definitions

components? Components - Reference objects

ai: Operation

Describes a single API operation on a path.

Fields

tags? string[] - A list of tags for API documentation control

summary? string - A short summary of what the operation does

description? string - A description explanation of the operation behavior

operationId? string - Operation ID for referencing the operation

parameters? (Parameter|Reference)[] - A list of parameters that are applicable for this operation

requestBody? RequestBody|Reference - The request body applicable for this operation

responses? map<Response|Reference> - The list of possible responses as they are returned from executing this operation

ai: Parameter

Describes a single operation parameter.

Fields

name string - Name of the parameter

'in ParameterLocation - The location of the parameter

required? boolean - Whether the parameter is mandatory

description? string - A brief description of the parameter

allowEmptyValue? boolean - Whether empty value is allowed

style? EncodingStyle - Describes how a specific property value will be serialized depending on its type

explode? boolean - When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map

schema? Schema - Schema of the parameter

content? map<MediaType> - Content of the parameter

nullable? boolean - Null value is allowed

ai: ParameterSchema

Closed record

Defines a HTTP parameter schema (can be query parameter or path parameters).

Fields

location PATH|QUERY - Whether the parameter is a path or query parameter

description? string - A brief description of the parameter

required? boolean - Whether the parameter is mandatory

style? EncodingStyle - Describes how a specific property value will be serialized depending on its type

explode? boolean - When this is true, property values of type array or object generate separate parameters for each value of the array, or key-value-pair of the map.

nullable? boolean - Null value is allowed

allowEmptyValue? boolean - Whether empty value is allowed

mediaType? string - Content type of the schema

schema JsonSubSchema - Parameter schema

ai: PathItem

Describes a single path item.

Fields

description? string - Description of the path item

summary? string - Summary of the path item

get? Operation - GET operation

post? Operation - POST operation

put? Operation - PUT operation

delete? Operation - DELETE operation

options? Operation - OPTIONS operation

head? Operation - HEAD operation

patch? Operation - PATCH operation

trace? Operation - TRACE operation

servers? Server[] - Server information for the path

parameters? (Parameter|Reference)[] - A list of parameters that are applicable for all the operations described under this path item

\$ref? never - Not allowed $ref

ai: Paths

Map of pathItem objects.

Fields

PathItem|Reference... - Rest field

ai: PrimitiveInputSchema

Closed record

Defines a primitive input field in the schema.

Fields

Fields Included from *BaseInputTypeSchema

type InputType
description string
default json
nullable boolean

'type STRING|INTEGER|NUMBER|BOOLEAN|NULL - Input data type. Should be one of STRING, INTEGER, NUMBER, or BOOLEAN.

format? string - Format of the input. This is not applicable for BOOLEAN type.

pattern? string - Pattern of the input. This is only applicable for STRING type.

'enum? (PrimitiveType?)[] - Enum values of the input. This is only applicable for STRING type.

default? PrimitiveType - Default value of the input

ai: QueryMatch

Closed record

Represents a match result with similarity score.

Fields

chunk Chunk - The chunk that matched the query

similarityScore float - Similarity score indicating chunk relevance to the query

ai: Reference

Defines a reference object.

Fields

\$ref string - Reference to a component

summary? string - Short description of the target component

'xml? XmlSchema - Xml schema

description? string - Detailed description of the target component

ai: RequestBody

Describes a single request body.

Fields

description? string - A brief description of the request body. This could contain examples of use.

content map<MediaType> - The content of the request body.

required? boolean - Whether the request body is mandatory in the request.

ai: RequestBodySchema

Closed record

Fields

description? string - A brief description of the request body

mediaType? string - Content type of the request body

schema JsonSubSchema - Request body schema

ai: Response

Describes a single response from an API Operation.

Fields

description? string - A short description of the response

headers? map<Header|Reference> - A map containing schema of the response headers

content? map<MediaType> - A map containing the structure of the response body

\$ref? never - Not allowed $ref

ai: Responses

Describes the responses from an API Operation.

Fields

default? Response|Reference - Default response for the API Operation

Response|Reference... - Rest field

ai: Server

Server information object.

Fields

url string - A URL to the target host

description? string - An optional string describing the host designated by the URL

ai: SparseVector

Closed record

Represents a sparse vector storing only non-zero values with their corresponding indices.

Fields

indices int[] - Array of indices where non-zero values are located

values Vector - Array of non-zero floating-point values corresponding to the indices

ai: StringSchema

Closed record

String schema object.

Fields

Fields Included from *BasePrimitiveTypeSchema

properties never
items never
type string
anyOf never
oneOf never
allOf never
not never
description string
default json
nullable boolean
xml XmlSchema
\$ref never
anydata...

'type STRING(default STRING) - Type of the string schema

format? string - Format of the string

minLength? int - Minimum length of the string value

maxLength? int - Maximum length of the string value

pattern? string - Regular expression pattern of the string value

'enum? (PrimitiveType?)[] - Enum values of the string value

ai: SystemPrompt

Closed record

Represents the system prompt given to the agent.

Fields

role string - The role or responsibility assigned to the agent

instructions string - Specific instructions for the agent

ai: TextChunk

Closed record

Represents a chunk of text within a document.

Fields

Fields Included from *Chunk

type string
metadata Metadata
content anydata

'typereadonly "text-chunk" (default "text-chunk") - Fixed type for the text chunk

content string - The text content of the chunk

ai: TextDocument

Closed record

Represents documents containing plain text content

Fields

Fields Included from *Document

type string
metadata Metadata
content anydata

'typereadonly "text" (default "text") - Fixed type for the text document

content string - The text content of the document

ai: Tool

Closed record

This is the tool used by LLMs during reasoning. This tool is same as the Tool record, but it has a clear separation between the variables that should be generated with the help of the LLMs and the constants that are defined by the users.

Fields

name string - Name of the tool

description string - Description of the tool

variables? map<json> - Variables that should be generated with the help of the LLMs

constants map<json>(default {}) - Constants that are defined by the users

caller function() () - Function that should be called to execute the tool

ai: ToolAnnotationConfig

Closed record

Defines the configuration of the Tool annotation.

Fields

name? string - The name of the tool. If not provided, defaults to the function pointer name.

description? string - A description of the tool. This is used by LLMs to understand the tool's behavior.
If not provided, the doc comment used as the description.

parameters? ObjectInputSchema? - The input schema expected by the tool. If the tool does not expect any input, this should be null.
If not provided, the input schema is generated automatically.

ai: ToolConfig

Closed record

Defines a tool. This is the only tool type directly understood by the agent. All other tool types are converted to this type using toolkits.

Fields

name string - Name of the tool

description string - A description of the tool. This is used by the LLMs to understand the behavior of the tool.

parameters map<json>?(default ()) - Input schema expected by the tool. If the tool doesn't expect any input, this should be null.

caller FunctionTool - Pointer to the function that should be called when the tool is invoked.

ai: ToolExecutionResult

Closed record

Represent the execution result of a tool.

Fields

result any|error - Return value of the tool

ai: ToolOutput

Closed record

Output from executing an action

Fields

value anydata|error - Output value the tool

ai: VectorEntry

Closed record

Represents a vector entry combining an embedding with its source chunk.

Fields

id? string - Optional unique identifier for the vector entry

embedding Embedding - The vector representation of the chunk content

chunk Chunk - The chunk associated with the embedding

ai: VectorMatch

Closed record

Represents a vector match result with similarity score.

Fields

Fields Included from *VectorEntry

id string
embedding Embedding
chunk Chunk

similarityScore float - Similarity score indicating how closely the vector matches the query

ai: VectorStoreQuery

Closed record

Defines a query to the vector store with an embedding vector and optional metadata filters. Supports precise search operations by combining vector similarity with metadata conditions.

Fields

embedding Embedding - The vector to use for similarity search

filters? MetadataFilters - Optional metadata filters to refine the search results.

ai: Wso2ProviderConfig

Closed record

Represents configuratations of WSO2 provider.

Fields

serviceUrl string - The URL for the WSO2 AI service

accessToken string - Access token for accessing WSO2 AI service

ai: XmlSchema

Closed record

Fields

name? string - Replaces the name of the element/attribute used for the described schema property.

namespace? string - The URI of the namespace definition.

prefix? string - The prefix to be used for the name.

attribute? boolean - Declares whether the property definition translates to an attribute instead of an element.

wrapped? boolean - May be used only for an array definition.

ai: UnsupportedOpenApiVersion

Distinct

OpenApiParsingError

Errors due to unsupported OpenAPI specification version.

ai: UnsupportedSerializationError

Distinct

OpenApiParsingError

Errors occurred due to unsupported path parameter serializations.

Object types

ai: BaseToolKit

Distinct

Allows implmenting custom toolkits by extending this type. Toolkits can help to define new types of tools so that agent can understand them.

getTools

Isolated Function

function getTools() returns ToolConfig[]

Useful to retrieve the Tools extracted from the Toolkit.

Return Type

ToolConfig[] - An array of Tools

ai: EmbeddingProvider

Distinct

Represents an embedding provider that converts chunk into vector embeddings for similarity search.

embed

Isolated FunctionRemote Function

function embed(Chunk chunk) returns Embedding|Error

Converts the given chunk into a vector embedding.

Parameters

chunk Chunk - The chunk to be convert into an embedding

Return Type

Embedding|Error - The embedding vector representation on success, or an ai:Error if the operation fails

batchEmbed

Isolated FunctionRemote Function

function batchEmbed(Chunk[] chunks) returns Embedding[]|Error

Converts a batch of chunks into vector embeddings.

Parameters

chunks Chunk[] - The array of chunks to be converted into embeddings

Return Type

Embedding[]|Error - An array of embeddings on success, or an ai:Error if the operation fails

ai: KnowledgeBase

Distinct

Represents a knowledge base for managing chunk indexing and retrieval operations.

ingest

Isolated Function

function ingest(Chunk[] chunks) returns Error?

Ingests a collection of chunks.

Parameters

chunks Chunk[] - The array of chunk to index

Return Type

Error? - An ai:Error if indexing fails; otherwise, nil

retrieve

Isolated Function

function retrieve(string query, MetadataFilters? filters) returns QueryMatch[]|Error

Retrieves relevant chunks for the given query.

Parameters

query string - The text query to search for

filters MetadataFilters? (default ()) - Optional metadata filters to apply during retrieval

Return Type

QueryMatch[]|Error - An array of matching chunks with similarity scores, or an ai:Error if retrieval fails

ai: Memory

Represents the memory interface for the agents.

get

Isolated Function

function get(string sessionId) returns ChatMessage[]|MemoryError

Retrieves all stored chat messages.

Parameters

sessionId string - The ID associated with the memory

Return Type

ChatMessage[]|MemoryError - An array of messages or an ai:Error

update

Isolated Function

function update(string sessionId, ChatMessage message) returns MemoryError?

Adds a chat message to the memory.

Parameters

sessionId string - The ID associated with the memory

message ChatMessage - The message to store

Return Type

MemoryError? - nil on success, or an ai:Error if the operation fails

delete

Isolated Function

function delete(string sessionId) returns MemoryError?

Deletes all stored messages.

Parameters

sessionId string - The ID associated with the memory

Return Type

MemoryError? - nil on success, or an ai:Error if the operation fails

ai: ModelProvider

Distinct

Represents an extendable client for interacting with an AI model.

chat

Isolated FunctionRemote Function

function chat(ChatMessage[]|ChatUserMessage messages, ChatCompletionFunctions[] tools, string? stop) returns ChatAssistantMessage|Error

Sends a chat request to the model with the given messages and tools.

Parameters

messages ChatMessage[]|ChatUserMessage - List of chat messages or a user message

tools ChatCompletionFunctions[] (default []) - Tool definitions to be used for the tool call

stop string? (default ()) - Stop sequence to stop the completion

Return Type

ChatAssistantMessage|Error - Function to be called, chat response or an error in-case of failures

generate

Isolated FunctionRemote Function

function generate(Prompt prompt, typedesc<anydata> td) returns td|Error

Sends a chat request to the model and generates a value that belongs to the type corresponding to the type descriptor argument.

Parameters

prompt Prompt - The prompt to use in the chat request

td typedesc<anydata> (default <>) - Type descriptor specifying the expected return type format

Return Type

td|Error - Generates a value that belongs to the type, or an error if generation fails

ai: Prompt

Raw template type for prompts.

Fields

Fields Included from *RawTemplate

strings string[] & readonly
insertions any|error[]

strings string[] & readonly - The fixed string parts of the template.

insertions (anydata|Document|Document[]|Chunk|Chunk[])[] - The insertions in the template. Array of values to be inserted into the template, can be anydata, Document, or Chunk types

ai: Retriever

Distinct

Represents chunk retriever that finds relevant chunks based on query similarity.

retrieve

Isolated Function

function retrieve(string query, MetadataFilters? filters) returns QueryMatch[]|Error

Retrieves relevant chunks for the given query.

Parameters

query string - The text query to search for

filters MetadataFilters? (default ()) - Optional metadata filters to apply during retrieval

Return Type

QueryMatch[]|Error - An array of matching chunks with similarity scores, or an ai:Error if retrieval fails

ai: VectorStore

Distinct

Represents a vector store that provides persistence, management, and search capabilities for vector embeddings.

add

Isolated Function

function add(VectorEntry[] entries) returns Error?

Adds vector entries to the store.

Parameters

entries VectorEntry[] - The array of vector entries to add

Return Type

Error? - An ai:Error if the operation fails; otherwise, nil

query

Isolated Function

function query(VectorStoreQuery query) returns VectorMatch[]|Error

Searches for vectors in the store that are most similar to a given query.

Parameters

query VectorStoreQuery - The vector store query that specifies the search criteria

Return Type

VectorMatch[]|Error - An array of matching vectors with their similarity scores, or an ai:Error if the operation fails

delete

Isolated Function

function delete(string id) returns Error?

Deletes a vector entry from the store by its unique ID.

Parameters

id string - The unique identifier of the vector entry to delete

Return Type

Error? - An ai:Error if the operation fails; otherwise, nil

Union types

ai: PrimitiveTypeSchema

IntegerSchema|NumberSchema|StringSchema|BooleanSchema

PrimitiveTypeSchema

Primitive type schema object.

ai: ObjectSchema

ObjectSchemaType1|ObjectSchemaType2

ObjectSchema

Defines an object schema.

ai: Schema

Schema

Defines a OpenAPI schema.

ai: Embedding

Vector|SparseVector|HybridVector

Embedding

Represents possible vector types.

ai: ChatMessage

ChatUserMessage|ChatSystemMessage|ChatAssistantMessage|ChatFunctionMessage

ChatMessage

Chat message record.

ai: PrimitiveType

int|string|boolean|float|decimal

PrimitiveType

Primitive types supported by the Tool schemas.

ai: JsonInputSchema

JsonInputSchema

Defines a json input schema

ai: JsonSubSchema

JsonInputSchema|PrimitiveInputSchema|ConstantValueSchema

JsonSubSchema

Defines a json sub schema

Array types

ai: Vector

float[]

Vector

Represents a dense vector with floating-point values.

Function types

ai: FunctionTool

function() ()

FunctionTool

Represents a type alias for an isolated function, representing a function tool.

String types

ai: Url

string

Url

Represents a URL.

Import

import ballerina/ai;

Other versions

1.1.1

1.1.0 1.0.0

Metadata

Released date: 2 days ago

Version: 1.1.1

License: Apache-2.0

Compatibility

Platform: java21

Ballerina version: 2201.12.0

GraalVM compatible: Yes

Pull count

Total: 856

Current verison: 220

Weekly downloads

Source repository

Keywords

AI/Agent

Cost/Freemium

Agent

Contributors

Dependencies

ballerina/math.vector/1.2.0 ballerina/url/2.6.0 ballerina/time/2.7.0

Dependents

ballerinax/ai.azure/1.1.0 ballerinax/ai.openai/1.2.0 ballerinax/ai.anthropic/1.1.0

Cookie policy

Delete policy

functions

classes

clients

serviceTypes

enums

listeners

annotations

configurables

records

errors

objectTypes

unionTypes

arrayTypes

functionTypes

stringTypes

ballerina/ai Ballerina library

Overview

Quickstart

Step 1: Import the module

Step 2: Define the System Prompt

Step 3: Define the Model Provider

Step 4: Define the tools

Step 5: Define the Memory

Step 6: Define the Agent

Step 7: Invoke the Agent

Examples

Functions

augmentUserQuery

Parameters

Return Type

chunkDocumentRecursively

Parameters

Return Type

executeTool

Parameters

Return Type

extractToolsFromOpenApiJsonSpec

Parameters

Return Type

extractToolsFromOpenApiSpecFile

Parameters

Return Type

getDefaultEmbeddingProvider

Return Type

getDefaultModelProvider

Return Type

getToolConfigs

Parameters

Return Type

getTools

Parameters

Return Type

parseOpenApiSpec

Parameters

Return Type

Classes

ai: Agent

Constructor

run

Parameters

Return Type

ai: HttpServiceToolKit

Constructor

getTools

Return Type

ai: InMemoryVectorStore

Constructor

add

Parameters

Return Type

query

Parameters

Return Type

delete

Parameters

Return Type

ai: McpToolKit

callTool

Parameters

getTools