Modules

ai.observe

Module ai.observe

ballerina/ai.observe Ballerina library

1.17.0

Functions

createAgentAuthenticationSpan

Isolated Function

function createAgentAuthenticationSpan(string flowId) returns AgentAuthenticationSpan

Creates a span representing the agent authentication process (AuthN).

Parameters

flowId string - The unique identifier for the authentication flow

Return Type

AgentAuthenticationSpan - An AgentAuthenticationSpan instance

createChatSpan

Isolated Function

function createChatSpan(string llmModel) returns ChatSpan

Creates a span representing a chat model interaction.

Parameters

llmModel string - The name of the LLM or chat model used

Return Type

ChatSpan - A ChatSpan instance representing the span

createCreateAgentIdentitySpan

Isolated Function

function createCreateAgentIdentitySpan(string agentName) returns CreateAgentIdentitySpan

Creates a span representing the creation of an agent identity.

Parameters

agentName string - The name of the agent being created

Return Type

CreateAgentIdentitySpan - A CreateAgentIdentitySpan instance

createCreateAgentSpan

Isolated Function

function createCreateAgentSpan(string agentName) returns CreateAgentSpan

Creates a span representing the creation of an AI agent.

Parameters

agentName string - The name of the agent being created

Return Type

CreateAgentSpan - A CreateAgentSpan instance representing the span

createCreateKnowledgeBaseSpan

Isolated Function

function createCreateKnowledgeBaseSpan(string kbName) returns CreateKnowledgeBaseSpan

Creates a span representing the creation of a knowledge base.

Parameters

kbName string - The name of the knowledge base being created

Return Type

CreateKnowledgeBaseSpan - A CreateKnowledgeBaseSpan instance representing the span

createEmbeddingSpan

Isolated Function

function createEmbeddingSpan(string embeddingModel) returns EmbeddingSpan

Creates a span representing an embedding generation operation.

Parameters

embeddingModel string - The embedding model name or identifier

Return Type

EmbeddingSpan - An EmbeddingSpan instance representing the span

createExchangeTokenSpan

Isolated Function

function createExchangeTokenSpan() returns ExchangeTokenSpan

Creates a span representing the exchange of an authorization code for a token.

Return Type

ExchangeTokenSpan - An ExchangeTokenSpan instance

createExecuteToolSpan

Isolated Function

function createExecuteToolSpan(string toolName) returns ExecuteToolSpan

Creates a span representing the execution of an AI tool.

Parameters

toolName string - The name of the tool being executed

Return Type

ExecuteToolSpan - An ExecuteToolSpan instance representing the span

createGenerateContentSpan

Isolated Function

function createGenerateContentSpan(string llmModel) returns GenerateContentSpan

Creates a span representing a generate content LLM interaction.

Parameters

llmModel string - The name of the LLM or chat model used

Return Type

GenerateContentSpan - A GenerateContentSpan instance representing the span

createInvokeAgentSpan

Isolated Function

function createInvokeAgentSpan(string agentName) returns InvokeAgentSpan

Creates a span representing the invocation of an AI agent.

Parameters

agentName string - The name of the agent being invoked

Return Type

InvokeAgentSpan - An InvokeAgentSpan instance representing the span

createInvokeAuthorizeEndpointSpan

Isolated Function

function createInvokeAuthorizeEndpointSpan(string organization) returns InvokeAuthorizeEndpointSpan

Creates a span representing an invocation of the OIDC/OAuth2 authorization endpoint.

Parameters

organization string - The root organization handle or tenant name

Return Type

InvokeAuthorizeEndpointSpan - An InvokeAuthorizeEndpointSpan instance

createKnowledgeBaseIngestSpan

Isolated Function

function createKnowledgeBaseIngestSpan(string kbName) returns KnowledgeBaseIngestSpan

Creates a span representing ingestion into a knowledge base.

Parameters

kbName string - The name of the knowledge base being ingested into

Return Type

KnowledgeBaseIngestSpan - A KnowledgeBaseIngestSpan instance representing the span

createKnowledgeBaseRetrieveSpan

Isolated Function

function createKnowledgeBaseRetrieveSpan(string kbName) returns KnowledgeBaseRetrieveSpan

Creates a span representing a retrieval operation from a knowledge base.

Parameters

kbName string - The name of the knowledge base being queried

Return Type

KnowledgeBaseRetrieveSpan - A KnowledgeBaseRetrieveSpan instance representing the span

createRequestHumanApprovalSpan

Isolated Function

function createRequestHumanApprovalSpan(string sessionId) returns RequestHumanApprovalSpan

Creates a span representing a run pausing to request human approval.

Parameters

sessionId string - The session/conversation the pause belongs to

Return Type

RequestHumanApprovalSpan - A RequestHumanApprovalSpan instance

createResolveHumanApprovalSpan

Isolated Function

function createResolveHumanApprovalSpan(string sessionId) returns ResolveHumanApprovalSpan

Creates a span representing a paused run being resumed with the human's decisions.

Parameters

sessionId string - The session/conversation the resume belongs to

Return Type

ResolveHumanApprovalSpan - A ResolveHumanApprovalSpan instance

createValidateTokenSpan

Isolated Function

function createValidateTokenSpan(string provider) returns ValidateTokenSpan

Creates a span representing the validation of an access token.

Parameters

provider string - The Identity Server or Authority that issued the token

Return Type

ValidateTokenSpan - A ValidateTokenSpan instance

createValidateToolAuthorizationSpan

Isolated Function

function createValidateToolAuthorizationSpan(string toolName) returns ValidateToolAuthorizationSpan

Creates a span representing the validation of agent permissions for a specific tool.

Parameters

toolName string - The name of the tool being authorized

Return Type

ValidateToolAuthorizationSpan - A ValidateToolAuthorizationSpan instance

getCurrentAiSpan

Isolated Function

function getCurrentAiSpan() returns AiSpan?

Retrieves the current active AI span, if any.

Returns the AiSpan associated with the current execution context. If tracing is not enabled or no span exists for the current context, returns ().

Return Type

AiSpan? -
- The current active AI span, or () if none is active

Classes

ai.observe: AgentAuthenticationSpan

Isolated

Represents a tracing span for an API-driven authentication flow.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addAgentIdentity

Isolated Function

function addAgentIdentity(string agentId, string authenticatorId)

Records the identity and authenticator used.

Parameters

agentId string - The unique identifier of the agent

authenticatorId string - The ID of the authenticator (e.g., BasicAuth)

close

Isolated Function

function close(error? err)

Closes the span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: ChatSpan

Isolated

Chat-specific LLM span implementation for chat operations.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *LlmSpan

addProvider

Isolated Function

function addProvider(string providerName)

Records the provider name used for the request.

Parameters

providerName string - The name of the AI provider/service (for example: openai)

addTemperature

Isolated Function

function addTemperature(float|decimal temperature)

Records the temperature setting used for the request.

Parameters

temperature float|decimal - The temperature value controlling randomness

addInputMessages

Isolated Function

function addInputMessages(json messages)

Records the input messages payload for the request.

Parameters

messages json - The input messages sent to the model

addOutputMessages

Isolated Function

function addOutputMessages(json messages)

Records the output messages payload produced by the model.

Parameters

messages json - The output messages returned by the model

addResponseModel

Isolated Function

function addResponseModel(string modelName)

Records the model name used for the response.

Parameters

modelName string - The model identifier/name used to generate the response (for example: gpt-40-2024)

addTools

Isolated Function

function addTools(json[] tools)

Records the tools schema send to the model.

Parameters

tools json[] - An array of tool schemas sent the the model

addResponseId

Isolated Function

function addResponseId(string|int id)

Records the response identifier assigned by the provider.

Parameters

id string|int - The provider-assigned response identifier

addInputTokenCount

Isolated Function

function addInputTokenCount(int count)

Records the count of input tokens consumed by the request.

Parameters

count int - Number of input tokens consumed

addOutputTokenCount

Isolated Function

function addOutputTokenCount(int count)

Records the count of output tokens produced by the response.

Parameters

count int - Number of output tokens produced

addFinishReason

Isolated Function

function addFinishReason(string|string[] reason)

Records the finish reason(s) returned by the model.

Parameters

reason string|string[] - A finish reason string or an array of reasons returned by the model

addOutputType

Isolated Function

function addOutputType(OutputType outputType)

Sets the response output type (e.g., text or json).

Parameters

outputType OutputType - The output type describing the response format

addStopSequence

Isolated Function

function addStopSequence(string|string[] stopSequence)

Records one or more stop sequences supplied to the model.

Parameters

stopSequence string|string[] - A single stop sequence or an array of stop sequences

close

Isolated Function

function close(error? err)

Closes the span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: CreateAgentIdentitySpan

Isolated

Represents a tracing span for the creation and configuration of an agent's identity.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function

function addId(string? agentId)

Records the unique agent identifier assigned by the identity system.

Parameters

agentId string? - The unique agent identifier (e.g., a UUID or system ID)

close

Isolated Function

function close(error? err)

Closes the span and records the final execution status.

Parameters

err error? (default ()) - An optional error if the identity creation process failed

ai.observe: CreateAgentSpan

Isolated

Represents a tracing span for creating an agent.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function

function addId(string agentId)

Records the agent ID assigned after creation.

Parameters

agentId string - The agent identifier

addSystemInstructions

Isolated Function

function addSystemInstructions(string instructions)

Records system instruction of the agent.

Parameters

instructions string - The system instructions string

addTools

Isolated Function

function addTools(json tools)

Records the tools used by the agent.

Parameters

tools json - Tools used by the agent

close

Isolated Function

function close(error? err)

Closes the agent creation span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: CreateKnowledgeBaseSpan

Isolated

Represents a tracing span for creating a knowledge base.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function

function addId(string|int id)

Records the knowledge base ID assigned after creation

Parameters

id string|int - The knowledge base identifier

close

Isolated Function

function close(error? err)

Closes the knowledge base creation span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: EmbeddingSpan

Isolated

Represents a tracing span for embedding model operations.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addResponseModel

Isolated Function

function addResponseModel(string model)

Records the response model name used for the embedding.

Parameters

model string - The model identifier/name used to generate the embedding

addProvider

Isolated Function

function addProvider(string providerName)

Records the provider name used for the embedding request.

Parameters

providerName string - The name of the AI provider/service (for example: openai)

addInputContent

Isolated Function

function addInputContent(anydata content)

Records the input content for the embedding request.

Parameters

content anydata - The input content to be embedded

addInputTokenCount

Isolated Function

function addInputTokenCount(int count)

Records the input token count for the embedding request.

Parameters

count int - Number of input tokens consumed

close

Isolated Function

function close(error? err)

Closes the embedding span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: ExchangeTokenSpan

Isolated

Represents a tracing span for exchanging an authorization code for an access token.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addExchangeDetails

Isolated Function

function addExchangeDetails(string clientId)

Records the details of the token exchange including PKCE verification.

Parameters

clientId string - The OAuth2 client identifier

close

Isolated Function

function close(error? err)

Closes the span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: ExecuteToolSpan

Isolated

Represents a tracing span for executing a tool.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function

function addId(string|int toolCallId)

Records the tool call ID of the execution.

Parameters

toolCallId string|int - The tool call identifier

addDescription

Isolated Function

function addDescription(string description)

Records the tool description of the execution.

Parameters

description string - The tool description string

addType

Isolated Function

function addType(ToolType toolType)

Records the tool type of the execution.

Parameters

toolType ToolType - The tool type

addArguments

Isolated Function

function addArguments(json arguments)

Records arguments of the tool execution.

Parameters

arguments json - The tool arguments

addOutput

Isolated Function

function addOutput(anydata output)

Records output of the tool execution.

Parameters

output anydata - The output produced by the tool

addToolKitName

Isolated Function

function addToolKitName(string mcpToolkit)

Records the toolkit name.

Parameters

mcpToolkit string - The name of the ai:ToolKit the tool belongs to.

close

Isolated Function

function close(error? err)

Closes the tool execution span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: GenerateContentSpan

Isolated

Generate-content specific LLM span implementation.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *LlmSpan

addProvider

Isolated Function

function addProvider(string providerName)

Records the provider name used for the request.

Parameters

providerName string - The name of the AI provider/service (for example: openai)

addTemperature

Isolated Function

function addTemperature(float|decimal temperature)

Records the temperature setting used for the request.

Parameters

temperature float|decimal - The temperature value controlling randomness

addInputMessages

Isolated Function

function addInputMessages(json messages)

Records the input messages payload for the request.

Parameters

messages json - The input messages sent to the model

addOutputMessages

Isolated Function

function addOutputMessages(json messages)

Records the output messages payload produced by the model.

Parameters

messages json - The output messages returned by the model

addResponseModel

Isolated Function

function addResponseModel(string modelName)

Records the model name used for the response.

Parameters

modelName string - The model identifier/name used to generate the response (for example: gpt-40-2024)

addTools

Isolated Function

function addTools(json[] tools)

Records the tools schema send to the model.

Parameters

tools json[] - An array of tool schemas sent the the model

addResponseId

Isolated Function

function addResponseId(string|int id)

Records the response identifier assigned by the provider.

Parameters

id string|int - The provider-assigned response identifier

addInputTokenCount

Isolated Function

function addInputTokenCount(int count)

Records the count of input tokens consumed by the request.

Parameters

count int - Number of input tokens consumed

addOutputTokenCount

Isolated Function

function addOutputTokenCount(int count)

Records the count of output tokens produced by the response.

Parameters

count int - Number of output tokens produced

addFinishReason

Isolated Function

function addFinishReason(string|string[] reason)

Records the finish reason(s) returned by the model.

Parameters

reason string|string[] - A finish reason string or an array of reasons returned by the model

addOutputType

Isolated Function

function addOutputType(OutputType outputType)

Sets the response output type (e.g., text or json).

Parameters

outputType OutputType - The output type describing the response format

addStopSequence

Isolated Function

function addStopSequence(string|string[] stopSequence)

Records one or more stop sequences supplied to the model.

Parameters

stopSequence string|string[] - A single stop sequence or an array of stop sequences

close

Isolated Function

function close(error? err)

Closes the span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: InvokeAgentSpan

Isolated

Represents a tracing span for invoking an agent.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function

function addId(string agentId)

Records the agent ID of the invocation.

Parameters

agentId string - The agent identifier

addSystemInstruction

Isolated Function

function addSystemInstruction(string instruction)

Records system instruction of the agent.

Parameters

instruction string - The system instruction

addSessionId

Isolated Function

function addSessionId(string sessionId)

Records the session ID of the invocation.

Parameters

sessionId string - The session/conversation identifier

addInput

Isolated Function

function addInput(string query)

Records the input query of the agent invocation.

Parameters

query string - The input query string

addOutput

Isolated Function

function addOutput(OutputType outputType, json output)

Records the output of the agent invocation.

Parameters

outputType OutputType - The output type

output json - The output messages

close

Isolated Function

function close(error? err)

Closes the agent invocation span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: InvokeAuthorizeEndpointSpan

Isolated

Represents a tracing span for the initial OIDC/OAuth2 authorization request.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addProviderUrl

Isolated Function

function addProviderUrl(string url)

Records the URL of the identity provider used for this agent.

Parameters

url string - The base URL of the Identity Server

addAuthRequestDetails

Isolated Function

function addAuthRequestDetails(string clientId, string[]|string? scopes, string url, string 'resource, string? challenge)

Records parameters from the /authorize call including PKCE challenge.

Parameters

clientId string - The OAuth2 client identifier

scopes string[]|string? - The list of requested scopes

url string - The authorize endpoint URL of the Identity Server

'resource string (default "") - The resource indicator (e.g., booking_api)

challenge string? (default ()) - The PKCE code_challenge

close

Isolated Function

function close(error? err)

Closes the span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: KnowledgeBaseIngestSpan

Isolated

Represents a tracing span for ingesting data into a knowledge base.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function

function addId(string|int id)

Records the knowledge base ID for the ingest operation.

Parameters

id string|int - The knowledge base identifier

addInputChunks

Isolated Function

function addInputChunks(json chunks)

Records the input chunks provied/generated for the ingest operation

Parameters

chunks json - The input chunks to be ingested

close

Isolated Function

function close(error? err)

Closes the ingest span and records its final status

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: KnowledgeBaseRetrieveSpan

Isolated

Represents a tracing span for retrieving data from a knowledge base.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addId

Isolated Function

function addId(string|int id)

Records the knowledge base ID for the retrieve operation.

Parameters

id string|int - The knowledge base identifier

addInputQuery

Isolated Function

function addInputQuery(json query)

Records the input query for the retrieve operation.

Parameters

query json - The input query to retrieve data

addOutput

Isolated Function

function addOutput(json output)

Records the output retrieved from the knowledge base.

Parameters

output json - The retrieved result

addLimit

Isolated Function

function addLimit(int maxLimit)

Records the maximum limit for the retrieve operation.

Parameters

maxLimit int - The maximum number of results to retrieve

addFilter

Isolated Function

function addFilter(json filter)

Records the filter for the retrieve operation.

Parameters

filter json - The filter criteria for retrieval

close

Isolated Function

function close(error? err)

Closes the retrieve span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: RequestHumanApprovalSpan

Isolated

Represents a tracing span for a run pausing to request human approval of one or more tool calls.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addPendingCount

Isolated Function

function addPendingCount(int count)

Records how many tool calls are awaiting a human decision.

Parameters

count int - The number of pending approval requests

addRequests

Isolated Function

function addRequests(json requests)

Records the pending approval requests (tool name, arguments, and id per request).

Parameters

requests json - The pending approval requests

close

Isolated Function

function close(error? err)

Closes the request-human-approval span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: ResolveHumanApprovalSpan

Isolated

Represents a tracing span for resuming a paused run with the human's decisions.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addDecisions

Isolated Function

function addDecisions(json decisions)

Records the human's decisions being applied on resume (tool name and outcome per request).

Parameters

decisions json - The decisions applied in this resume

close

Isolated Function

function close(error? err)

Closes the resolve-human-approval span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: ValidateTokenSpan

Isolated

Represents a tracing span for validating an access token.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addValidationResult

Isolated Function

function addValidationResult(boolean? active, string? clientId, string? subject)

Records the result of the token validation.

Parameters

active boolean? - Whether the token is currently valid and not expired

clientId string? (default ()) - The client ID associated with the token

subject string? (default ()) - The agent or user identifier (sub claim)

close

Isolated Function

function close(error? err)

Closes the span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

ai.observe: ValidateToolAuthorizationSpan

Isolated

Represents a tracing span for validating agent permissions (scopes) for a tool.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

addScopeCheck

Isolated Function

function addScopeCheck(string[] required, string[] granted)

Records the comparison between required and granted scopes.

Parameters

required string[] - The scopes required to run the tool

granted string[] - The scopes present in the agent's current token

close

Isolated Function

function close(error? err)

Closes the span and records its final status.

Parameters

err error? (default ()) - Optional error that indicates if the operation failed

Enums

ai.observe: OutputType

Represents the type of output produced by an LLM.

Members

TEXT - Represents a plain text output

JSON - Represents a structured JSON output

ai.observe: ToolType

Identifies the type of tool used by an agent.

Members

FUNCTION - Represents a function tool

EXTENTION - Represents a tool that directly invokes external APIs, such as an MCP server.

Object types

ai.observe: AiSpan

Distinct

Represents an AI tracing span that allows adding tags and closing the span.

close

Isolated Function

function close(error? err)

Closes the span and records its final status.

Parameters

err error? (default ()) -

ai.observe: LlmSpan

Distinct

Represents an LLM-specific tracing span for LLM calls.

addTag

Isolated Function

function addTag("gen_ai.hitl.decisions"|"gen_ai.hitl.requests"|"gen_ai.hitl.pending_count"|"gen_ai.token.validation.method"|"gen_ai.identity.provider"|"gen_ai.auth.validate_scope"|"gen_ai.auth.code_verifier"|"gen_ai.auth.code"|"gen_ai.auth.token_exchange"|"gen_ai.auth.agent_authenticate"|"gen_ai.auth.authenticator_id"|"gen_ai.auth.flow_id"|"gen_ai.auth.granted_scopes"|"gen_ai.auth.required_scopes"|"gen_ai.auth.token_status"|"gen_ai.auth.scopes"|"gen_ai.auth.pkce_method"|"gen_ai.auth.pkce_challenge"|"gen_ai.auth.resource"|"gen_ai.auth.client_id"|"gen_ai.knowledge_base.retrieve.input.filter"|"gen_ai.knowledge_base.retrieve.input.limit"|"gen_ai.knowledge_base.retrieve.output"|"gen_ai.knowledge_base.retrieve.input.query"|"gen_ai.knowledge_base.ingest.input.chunks"|"gen_ai.knowledge_base.id"|"gen_ai.knowledge_base.name"|"gen_ai.input.tools"|"gen_ai.input.content"|"gen_ai.tool.toolkit.name"|"gen_ai.tool.output"|"gen_ai.tool.arguments"|"gen_ai.tool.type"|"gen_ai.tool.description"|"gen_ai.tool.name"|"gen_ai.tool.call.id"|"gen_ai.agent.tools"|"gen_ai.agent.name"|"gen_ai.agent.id"|"gen_ai.system_instructions"|"gen_ai.output.messages"|"gen_ai.input.messages"|"gen_ai.usage.output_tokens"|"gen_ai.usage.input_tokens"|"gen_ai.response.id"|"gen_ai.response.finish_reasons"|"gen_ai.request.temperature"|"gen_ai.request.stop_sequences"|"gen_ai.response.model"|"gen_ai.request.model"|"gen_ai.output.type"|"gen_ai.conversation.id"|"gen_ai.provider.name"|"gen_ai.operation.name" key, anydata value) returns ()

Adds a tag to the span.

Method included from *AiSpan

close

Isolated Function

function close(error|() err) returns ()

Closes the span and records its final status.

Method included from *AiSpan

addProvider

Isolated Function

function addProvider(string providerName)

Records the provider name used for the request.

Parameters

providerName string - The name of the AI provider/service (for example: openai)

addTemperature

Isolated Function

function addTemperature(float|decimal temperature)

Records the temperature setting used for the request.

Parameters

temperature float|decimal - The temperature value controlling randomness

addInputMessages

Isolated Function

function addInputMessages(json messages)

Records the input messages payload for the request.

Parameters

messages json - The input messages sent to the model

addOutputMessages

Isolated Function

function addOutputMessages(json messages)

Records the output messages payload produced by the model.

Parameters

messages json - The output messages returned by the model

addResponseModel

Isolated Function

function addResponseModel(string modelName)

Records the model name used for the response.

Parameters

modelName string - The model identifier/name used to generate the response (for example: gpt-40-2024)

addResponseId

Isolated Function

function addResponseId(string|int id)

Records the response identifier assigned by the provider.

Parameters

id string|int - The provider-assigned response identifier

addInputTokenCount

Isolated Function

function addInputTokenCount(int count)

Records the count of input tokens consumed by the request.

Parameters

count int - Number of input tokens consumed

addOutputTokenCount

Isolated Function

function addOutputTokenCount(int count)

Records the count of output tokens produced by the model.

Parameters

count int - Number of output tokens produced

addFinishReason

Isolated Function

function addFinishReason(string|string[] reason)

Records the finish reason(s) returned by the model.

Parameters

reason string|string[] - A finish reason string or an array of reasons returned by the model

addOutputType

Isolated Function

function addOutputType(OutputType outputType)

Records the response output type

Parameters

outputType OutputType - The output type describing the response format

addStopSequence

Isolated Function

function addStopSequence(string|string[] stopSequence)

Records one or more stop sequences supplied to the model

Parameters

stopSequence string|string[] - A single stop sequence or an array of stop sequences

addTools

Isolated Function

function addTools(json[] tools)

Records the tools schema send to the model

Parameters

tools json[] - An array of tool schemas sent the the model

Import

import ballerina/ai.observe;

Other versions

1.17.0

1.16.1 1.16.0 1.15.0 1.14.1

Metadata

Released date: 1 day ago

Version: 1.17.0

License: Apache-2.0

Security

No known vulnerabilities in libraries

Checked on 2026-11-11 via OSV.dev

Compatibility

Platform: java25

Ballerina version: 2201.14.0

GraalVM compatible: Yes

Pull count

Total: 69246

Current verison: 87

Weekly downloads

Source repository

Keywords

AI/Agent

Cost/Freemium

Agent

Vendor/N/A

Area/AI

Type/Connector

Contributors

Dependencies

ballerina/math.vector/1.2.0 ballerina/random/1.7.0 ballerina/observe/1.8.0

Cookie policy

Delete policy

functions

classes

enums

objectTypes

ballerina/ai.observe Ballerina library

Functions

createAgentAuthenticationSpan

Parameters

Return Type

createChatSpan

Parameters

Return Type

createCreateAgentIdentitySpan

Parameters

Return Type

createCreateAgentSpan

Parameters

Return Type

createCreateKnowledgeBaseSpan

Parameters

Return Type

createEmbeddingSpan

Parameters

Return Type

createExchangeTokenSpan

Return Type

createExecuteToolSpan

Parameters

Return Type

createGenerateContentSpan

Parameters

Return Type

createInvokeAgentSpan

Parameters

Return Type

createInvokeAuthorizeEndpointSpan

Parameters

Return Type

createKnowledgeBaseIngestSpan

Parameters

Return Type

createKnowledgeBaseRetrieveSpan

Parameters

Return Type

createRequestHumanApprovalSpan

Parameters

Return Type

createResolveHumanApprovalSpan

Parameters

Return Type

createValidateTokenSpan

Parameters

Return Type

createValidateToolAuthorizationSpan

Parameters

Return Type

getCurrentAiSpan

Return Type

Classes

ai.observe: AgentAuthenticationSpan

addTag

addAgentIdentity

Parameters

close

Parameters

ai.observe: ChatSpan

addTag

addProvider

Parameters

addTemperature

Parameters

addInputMessages

Parameters

addOutputMessages

Parameters

addResponseModel

Parameters

addTools

Parameters

addResponseId