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.

python

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.

python

from amrita_core import minimal_init

await minimal_init()

`set_config(config)`

The set_config() function applies a configuration to AmritaCore.

python

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.

python

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.

python

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()
create_agent() has no protocol parameter — it always builds a preset with the default protocol ("__main__", the OpenAI-compatible adapter). The provider is chosen by base_url + model; DeepSeek, Azure or any OpenAI-compatible endpoint works through the same adapter. To use the Anthropic wire format, construct a ModelPreset with protocol="anthropic" and pass it to AgentRuntime directly — see Model Adapters

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	Base context for preset fallback events (`PRESET_FALLBACK`); subclasses: `CompletionFallbackContext`, `ToolsFallbackContext`, `EmbeddingFallbackContext`

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.

python

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.

python

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.

python

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.

python

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.

python

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:

python

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.

API Reference ​

Core API Functions ​

load_amrita() ​

minimal_init() ​

set_config(config) ​

get_config() ​

create_agent() ​

Configuration ​

Chat Management ​

Types ​

Tools ​

Backends & Contexts ​

Agent Strategies ​

Events & Hooks ​

Presets & Tokenizers ​

Decorators ​

@simple_tool ​

@on_tools ​

@on_event ​

@on_precompletion ​

@on_completion ​

Type Definitions ​

Predefined Types ​

Step-Loop Types (built-in ReAct) ​

Exception Types ​

Type Checking ​

API Reference

Core API Functions

`load_amrita()`

`minimal_init()`

`set_config(config)`

`get_config()`

`create_agent()`

Configuration

Chat Management

Types

Tools

Backends & Contexts

Agent Strategies

Events & Hooks

Presets & Tokenizers

Decorators

`@simple_tool`

`@on_tools`

`@on_event`

`@on_precompletion`

`@on_completion`

Type Definitions

Predefined Types

Step-Loop Types (built-in ReAct)

Exception Types

Type Checking