API Reference

This reference is organized by functional module. Each entry links to the class page for full documentation.

Core API Functions

load_amrita()

The load_amrita() function asynchronously loads MCP clients when MCP is enabled in the configuration. Tokenizers and adapters are already registered at import time — load_amrita() does not load them.

import asyncio
from amrita_core import load_amrita


async def main():
    await load_amrita()


asyncio.run(main())

Usage Notes:

• No longer requires init() to be called first (since v0.9.0rc1)
• Should be called after set_config() if custom configuration is used
• When MCP is enabled, it's required to call load_amrita()

minimal_init()

The minimal_init() function performs minimal initialization: it applies the config and loads MCP clients if enabled. Tokenizers and adapters are already registered at import time.

from amrita_core import minimal_init

await minimal_init()

set_config(config)

The set_config() function applies a configuration to AmritaCore.

from amrita_core.config import AmritaConfig, set_config

config = AmritaConfig()
set_config(config)

Parameters:

• config (AmritaConfig): The configuration object to set

Usage Notes:

• Should be called before load_amrita()

get_config()

The get_config() function retrieves the current AmritaCore configuration.

from amrita_core.config import get_config

config = get_config()
print(config.function_config.use_minimal_context)

Returns: AmritaConfig - The current configuration object

Usage Notes:

• Throws RuntimeError if AmritaCore is not initialized

create_agent()

The create_agent() factory function creates an agent with minimal parameters by automatically creating a temporary preset. This is the recommended entry point for building agents.

from amrita_core import create_agent

agent = create_agent(
    "https://api.example.com",  # Replace with your API URL
    "your-api-key",  # Replace with your API key
    model="gpt-4",  # Replace with your desired model
    model_config={"temperature": 0.7},
)

Parameters:

• base_url (str): The API endpoint URL
• api_key (str): The API key for authentication
• model (str, optional): The model to use. Defaults to "auto"
• train (str | None, optional): System prompt; defaults to built-in instructions
• model_config (ModelConfig | dict | None, optional): Optional model configuration. Defaults to None
• config (AmritaConfig | None, optional): Configuration for the agent. Defaults to global config
• **kwargs: Additional keyword arguments forwarded to AgentRuntime (e.g. strategy, template, session_id, backend)

Returns: AgentRuntime - Configured agent runtime instance

Usage Notes:

• The function automatically creates a temporary preset; use PresetManager for persistent presets
• The returned agent can be reused for multiple interactions via get_chatobject()

Configuration

Class	Description
AmritaConfig	Central configuration object (function_config / llm / cookie / builtin)
FunctionConfig	Functional behavior: context, tokenizer, tool call limit, MCP client
LLMConfig	LLM behavior: token limits, retries, fallbacks, memory summarization
CookieConfig	Cookie leak detection mechanism

Chat Management

Class	Description
ChatObject	Core class for individual conversations
ChatManager	Manages running ChatObject instances
ChatObjectMeta	Metadata model for ChatObject snapshots
SuspendEnum	Standardized breakpoint tags for suspend/resume

Types

Class	Description
Message	A single message in the conversation
SendMessageWrap	Iterable wrapper for the message list sent to the model
MemoryModel	Stores conversation history
ModelConfig	Model-specific behavior parameters
ModelPreset	Complete configuration for a specific model
ThinkingConfig	Thinking/reasoning configuration
TextContent	Text content within messages
ToolCall	An invocation of a tool
ToolResult	The result of a tool invocation
UniResponse	Unified response format
UniResponseUsage	Usage statistics for responses
EmbeddingChunk	Embedding vector returned by the embedding adapter
BaseModel	Base class for all data models

Tools

Class	Description
FunctionDefinitionSchema	Function definition schema (name, description, parameters)
ToolFunctionSchema	Complete function-calling schema (function + type + strict)
ToolData	Data model for registering tools (metadata + implementation)
ToolContext	Context passed to tool functions during execution
ToolsManager	Singleton tool registry
MultiToolsManager	Multi-instance tool registry with enable/disable support
MCPClient	MCP client for connecting to MCP servers
ClientManager	Manages a single MCP client
MultiClientManager	Manages multiple MCP clients

Backends & Contexts

Class	Description
BackendSlots	Bundles ability and memory backends for I/O
AbilityBackend	Abstract base for loading tools, MCP clients, and presets
MemoryBackend	Abstract base for loading and committing memory
LegacyBackend	Default in-process backend implementation
AbilityContext	Runtime ability state (tools, presets, MCP clients)
StateContext	Runtime session state (session_id, memory, ability)
DatabackendOptions	Fine-grained control over backend fetch/commit operations

Agent Strategies

Class	Description
AgentRuntime	Agent runtime wrapper returned by create_agent()
AgentStrategy	Abstract base class for agent strategies
StrategyContext	Context passed to strategy execution
BaseReActAgentStrategy	Base ReAct strategy implementation
ReActAgentStrategy	Standard ReAct strategy
HybridReActAgentStrategy	Hybrid ReAct strategy
NoActionAgentStrategy	Strategy that performs no actions

Events & Hooks

Class	Description
CompletionEvent	Fired after model completion (event type COMPLETION)
PreCompletionEvent	Fired before strategy run and completion (BEFORE_COMPLETION)
FallbackContext	Context for preset fallback events (PRESET_FALLBACK)

Presets & Tokenizers

Class	Description
PresetManager	Manages model presets
MultiPresetManager	Multi-instance preset management with testing support
BaseTokenizer	Abstract base class for custom tokenizers
ModelAdapter	Abstract base class for model adapters

Decorators

@simple_tool

The @simple_tool decorator is used to register a simple tool.

from amrita_core import simple_tool


@simple_tool
def add(a: int, b: int) -> int:
    """Add number

    Args:
        a (int): First number
        b (int): Second number
    """
    return a + b

Purpose: Register a simple tool with automatic schema inference from type annotations and docstrings.

Supported Parameter Types:

• Basic types: str, int, float, bool
• Literal types: Literal["a", "b"] → auto-generates string + enum constraint; Literal[1, 2, 3] likewise supports integer enum
• Pydantic BaseModel classes for complex nested structures
• Container types: List[T] (single-level only)
• Optional types: Optional[T] or T | None

Unsupported Types (will raise ValueError):

• Dict types (use Pydantic models instead)
• Nested containers (e.g., List[List[str]])
• Multi-type unions (e.g., str | int)
• Any or object types

Registration Behavior:

• Tools are registered to the global container during module loading
• Available to all sessions since registration happens before session creation
• For session-specific tool management, use direct MultiToolsManager operations instead

Usage Notes:

• The tool is registered with the name of the function
• The description of each parameter comes from the function's docstring (Google-style)
• All function parameters must have type annotations (no untyped parameters allowed)

@on_tools

The @on_tools decorator registers functions as callable tools for the agent.

from typing import Any

from amrita_core import on_tools
from amrita_core.tools.models import (
    FunctionDefinitionSchema,
    FunctionParametersSchema,
    FunctionPropertySchema,
)

DEFINITION = FunctionDefinitionSchema(
    name="Add number",
    description="Add two numbers",
    parameters=FunctionParametersSchema(
        type="object",
        properties={
            "a": FunctionPropertySchema(type="number", description="The first number"),
            "b": FunctionPropertySchema(type="number", description="The second number"),
        },
        required=["a", "b"],
    ),
)


@on_tools(DEFINITION)
async def add(data: dict[str, Any]) -> str:
    """Add two numbers"""
    return str(data["a"] + data["b"])

Purpose: Registers a function as an available tool that the agent can call with fine-grained control over the tool schema.

Registration Behavior:

• Like @simple_tool, registers to the global container during module loading
• Provides explicit control over tool schema definition
• Suitable for complex validation requirements not supported by @simple_tool

Usage Notes:

• Function must have proper type hints for parameters
• Function docstring becomes the tool description

@on_event

The @on_event decorator registers functions as event handlers.

from amrita_core.hook.on import on_event


@on_event()
def my_event_handler(event):
    # Handle custom events
    pass

Purpose: Registers a function to handle specific events during the processing pipeline.

@on_precompletion

The @on_precompletion decorator registers functions to run before the completion request is sent to the LLM.

from amrita_core.hook.event import PreCompletionEvent
from amrita_core.hook.on import on_precompletion


@on_precompletion().handle()
async def preprocess_request(event: PreCompletionEvent):
    # Modify the messages before sending to LLM
    print(event)

Purpose: Runs before sending the request to the LLM, allowing modification of messages or other preprocessing.

@on_completion

The @on_completion decorator registers functions to run after receiving the completion from the LLM.

from amrita_core.hook.event import CompletionEvent
from amrita_core.hook.on import on_completion


@on_completion().handle()
async def postprocess_response(event: CompletionEvent):
    # Process the response after receiving from LLM
    print(event)

Purpose: Runs after receiving the response from the LLM, allowing post-processing of the response.

Type Definitions

Predefined Types

AmritaCore provides several predefined types for consistency:

• BaseModel: Base class for all data models
• EmbeddingChunk: Represents an embedding vector returned by embedding adapter
• FunctionDefinitionSchema: Schema for function parameters
• MemoryModel: Stores conversation history
• ModelConfig: Model-specific configuration
• ModelPreset: Complete configuration for a specific model
• ChatManager: Manages running ChatObject instances
• ChatObjectMeta: Metadata model for ChatObject snapshots
• SuspendEnum: Standardized breakpoint tags for suspend/resume mechanism
• TextContent: Represents text content within messages
• ToolCall: Represents an invocation of a tool
• ToolContext: Provides context for tool execution
• ToolResult: Represents the result of a tool invocation
• ToolsManager: Manages registered tools
• UniResponse: Unified format for responses
• UniResponseUsage: Usage statistics for responses

Step-Loop Types (built-in ReAct)

• AgentRunState: Semantic step-level run state (plan, stall window, tokens)
• DAGNode: A sub-step of the task plan
• StepEvents: The mutable step lifecycle events (step_intro / step_leave / step_iteration / tool_call / tool_return) and StepAbortError

See Advanced → Step Loop for how they fit together.

Exception Types

AmritaCore may raise the following exceptions:

• RuntimeError: Raised when accessing configuration before initialization
• ValueError: Raised when invalid values are provided to functions
• TypeError: Raised when incorrect types are passed to functions

Type Checking

AmritaCore uses Pydantic models extensively for type validation. When creating custom components, ensure proper type annotations:

from typing import Optional
from amrita_core.types import BaseModel


class CustomConfig(BaseModel):
    param1: str
    param2: Optional[int] = None
    param3: list[str] = []

This API reference provides a comprehensive overview of the core AmritaCore interfaces, classes, and decorators. Each component is designed to work together to provide a flexible and powerful framework for building AI agents.