Module ai

ballerina/ai Ballerina library

1.0.0

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

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)

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: 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 -

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.

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: ParameterLocation

Members

QUERY

HEADER

PATH

ai: ROLE

Roles for the chat messages.

Members

SYSTEM

USER

ASSISTANT

FUNCTION

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.

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: 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? JsonInputSchema - 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 - 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 - 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: 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: 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: 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: 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: 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: 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: 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: 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: 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? JsonInputSchema - 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 JsonInputSchema?(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: 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: 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[] messages, ChatCompletionFunctions[] tools, string? stop) returns ChatAssistantMessage|LlmError

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

Parameters

messages ChatMessage[] - List of chat messages

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

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

Return Type

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

Union 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

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.

Function types

ai: FunctionTool

function() ()

FunctionTool

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

Import

import ballerina/ai;

Metadata

Released date: 18 days ago

Version: 1.0.0

License: Apache-2.0

Compatibility

Platform: java21

Ballerina version: 2201.12.0

GraalVM compatible: Yes

Pull count

Total: 0

Current verison: 133

Weekly downloads

Source repository

Keywords

AI/Agent

Cost/Freemium

Agent

Contributors

Other versions

1.0.0

Cookie policy

Delete policy

functions

classes

clients

serviceTypes

enums

listeners

annotations

configurables

records

errors

objectTypes

unionTypes

functionTypes

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

executeTool

Parameters

Return Type

extractToolsFromOpenApiJsonSpec

Parameters

Return Type

extractToolsFromOpenApiSpecFile

Parameters

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: MessageWindowChatMemory

Constructor

get

Parameters

Return Type

update

Parameters

Return Type

delete

Parameters

Return Type

ai: ToolStore

Constructor

execute

Parameters

Return Type

Fields

Clients

ai: ChatClient

Constructor

post chat

Parameters

Return Type

Service types

ai: ChatService

post chat

Parameters