Function Kernel API¶

The FunctionKernel is the unified tool-execution layer. It hosts three kinds of tools behind a single interface, each addressed by URI:

Python functions — python://<name>
REST endpoints — rest://<server>.<tool>
MCP tools — mcp://<server>.<tool>

Every tool has a Pydantic input and output model; the kernel validates and coerces arguments before a call and the return value after it, so callers always see well-typed data.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.

exception kavalai.functionkernel.FunctionKernelException[source]¶

Bases: WorkflowException

Raised by FunctionKernel when registering or calling a tool fails.

Covers errors such as unknown protocols, duplicate or unregistered tools, malformed tool URIs, argument validation failures and errors surfaced by the underlying REST/MCP/Python tool call.

kavalai.functionkernel.pythontool(func: Callable) → Callable[source]¶

Mark a function as a Kaval.AI Python tool.

Sets an internal flag (_is_kavalai_tool) on the function without altering its behaviour, so the decorated function remains directly callable as normal Python. Register it with FunctionKernel.register_python_tool() to expose it to workflows, after which it is addressed by the tool URI python://<name>.

Parameters:¶

func: Callable¶: The function to mark as a tool.

Returns:¶

The same function, flagged as a Kaval.AI tool.

class kavalai.functionkernel.ToolDefinition(*, name: str, description: str | None = None, input_model: type[BaseModel], output_model: type[BaseModel])[source]¶

Bases: BaseModel

name : str¶

description : str | None¶

input_model : Type[BaseModel]¶

output_model : Type[BaseModel]¶

to_dict(name_override: str | None = None) → dict[str, Any][source]¶

model_config : ClassVar[ConfigDict] = {}¶: Configuration for the model, should be a dictionary conforming to [ConfigDict][pydantic.config.ConfigDict].

class kavalai.functionkernel.Validator[source]¶

Bases: object

Helps converting and validating tool inputs and outputs. Allows only basic data types and pydantic models.

static create_model_from_signature(name: str, sig: Signature, is_input: bool = True) → type[BaseModel][source]¶

static create_model_from_schema(name: str, schema: dict[str, Any]) → type[BaseModel][source]¶

static validate_arguments(model: type[BaseModel], arguments: dict[str, Any]) → dict[str, Any][source]¶

static cast_result(result: Any, target_output_type: type | None, context_info: str = '') → Any[source]¶: Cast result to target output type if it’s a Pydantic model.

class kavalai.functionkernel.FunctionKernel[source]¶

Bases: object

Manages registration and execution of tools (REST, MCP, Python). Handles conversions and MCP session management.

register_rest_server(server: RestServer)[source]¶

register_rest_tool(server_name: str, tool_name: str, method: str, input_schema: dict[str, Any], output_schema: dict[str, Any], description: str | None = None)[source]¶

register_mcp_server(server: McpServer)[source]¶

register_python_tool(name: str, func: Callable)[source]¶

async call_tool(tool_uri: str, arguments: dict[str, Any] = None, output_type: type | None = None, **kwargs) → Any[source]¶: Unified tool call interface. Format: protocol://[name|module].function_name Example: python://kavalai.mytool.myfunc or rest://myrestserver.restfunction

async close()[source]¶: Cleanup all MCP sessions.

get_tool_definition(tool_uri: str) → ToolDefinition[source]¶

Resolve a tool URI to its ToolDefinition.

Format: protocol://[name|module].function_name Raises FunctionKernelException if the tool is not registered.

get_input_model(tool_uri: str) → type[BaseModel][source]¶: Return the input Pydantic model for a registered tool.

get_output_model(tool_uri: str) → type[BaseModel][source]¶: Return the output Pydantic model for a registered tool.

async get_tool_descriptions(allowed_tools: list[str] | None = None) → str[source]¶: Returns a string description of all registered tools as a JSON array for prompts.