API Reference
The AgenticAI Core SDK provides two categories of APIs:- Design-time models — Define your app structure, agents, tools, LLM configuration, memory stores, and environment variables before deployment.
- Runtime APIs — Access session context, environment variables, memory, logging, and tracing from within your tools and orchestrators during request processing.
Quick Start
The following examples show a minimal app definition and a tool implementation that uses runtime services.Define an app
Define an app
Implement a tool
Implement a tool
Deploy
Deploy
Design-Time APIs
Design-time models are the blueprint of your application. Use them to define app structure, configure agents, and set up tools, memory stores, and environment variables before deployment. The diagram below shows how the core models relate to each other. Core models:| Model | Purpose |
|---|---|
| App | Top-level application container. Defines orchestration strategy and holds agents. |
| Agent | AI agent definition. Configures behavior, tools, and LLM. |
| Tool | Agent capability. Supports MCP, inline, and library tool types. |
| LlmModel | LLM configuration. Specifies provider, model, and generation parameters. |
| Prompt | Agent instructions. Defines system prompt, custom behavior, and rules. |
| MemoryStore | Persistent storage. Configures schemas, scoping, and retention. |
| Model | Purpose |
|---|---|
| AppConfiguration | Advanced app features — streaming, attachments, filler messages. |
| AppNamespace | Logical groupings for scoping app variables. |
| AppVariable | Environment variables scoped to namespaces. |
| Icon | Visual identifiers for apps and agents. |
App
from agenticai_core.designtime.models.app import App, OrchestratorType, AppBuilder
The top-level container for your application. It holds agents, memory stores, namespaces, variables, and configuration.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | str | Yes | Application name. |
description | str | No | Application description. |
orchestrationType | OrchestratorType | No | Orchestration strategy. Default: platform-managed. |
ai_model | LlmModel | No | Default LLM model for the app. |
agents | list[Agent] | No | Agents in the application. |
app_icon | Icon | No | App icon. |
memory_stores | list[MemoryStore] | No | Persistent memory stores. |
app_namespaces | list[AppNamespace] | No | Logical variable namespaces. |
app_variables | list[AppVariable] | No | Environment variables. |
app_configuration | AppConfigurations | No | Advanced feature configuration. |
| Value | Description |
|---|---|
OrchestratorType.CUSTOM_SUPERVISOR | Custom supervisor orchestration using your AbstractOrchestrator implementation. |
| Method | Description |
|---|---|
.set_name(name) | Sets the application name. |
.set_description(desc) | Sets the application description. |
.set_orchestrator_type(type) | Sets the orchestration type. |
.set_agents(agents) | Sets the list of agents. |
.set_memory_stores(stores) | Sets the list of memory stores. |
.build() | Returns a dict suitable for App(**app_dict). |
Direct instantiation
Direct instantiation
Builder pattern
Builder pattern
Multi-agent application
Multi-agent application
Agent
from agenticai_core.designtime.models.agent import Agent, AgentRole, AgentSubType, AgentType, AgentBuilder
Defines an AI agent’s behavior, capabilities, and LLM configuration.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | str | Yes | Agent name. |
description | str | No | Agent description. |
role | AgentRole | No | Agent role in orchestration. |
sub_type | AgentSubType | No | Agent reasoning pattern. |
type | AgentType | No | Agent execution type. |
llm_model | LlmModel | No | LLM configuration for the agent. |
prompt | Prompt | No | System and custom instructions. |
tools | list[Tool] | No | Tools available to the agent. |
icon | Icon | No | Visual identifier. |
agent_config | AgentConfig | No | Advanced agent prompt overrides. |
| Enum | Values | Description |
|---|---|---|
AgentRole | SUPERVISOR, WORKER | Role in orchestration. |
AgentSubType | REACT | Reasoning pattern. |
AgentType | AUTONOMOUS | Execution mode. |
| Parameter | Type | Description |
|---|---|---|
react_prompt | str | Override for the ReAct reasoning prompt. |
planner_prompt | str | Override for the planner prompt. |
executor_prompt | str | Override for the executor prompt. |
agent.to_agent_meta() → AgentMeta — Returns a lightweight representation used for orchestrator registration.
Basic agent
Basic agent
Builder pattern
Builder pattern
Tool
from agenticai_core.designtime.models.tool import Tool, ToolBuilder
Defines a capability available to agents. Supports MCP tools (custom Python functions), inline tools, tool library tools, and more.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | str | Yes | Tool name. Must match the registered function name for MCP tools. |
description | str | No | Tool description shown to the agent. |
type | str | Yes | Tool type. See Tool types below. |
code_type | str | No | Code language for inline tools — javascript or python. |
func | str | No | Inline tool code body. |
return_direct | bool | No | If True, returns tool output directly without further agent processing. |
properties | list[dict] | No | Parameter definitions for toolLibrary tools. |
| Type | Description |
|---|---|
MCP | Custom Python function registered with @Tool.register. Runs as an MCP server tool. |
inlineTool | JavaScript or Python code that executes inline within the agent runtime. |
toolLibrary | Pre-built tool from the platform’s tool library. |
KNOWLEDGE | Knowledge base or RAG tool for semantic search. |
customTool | User-defined tool with custom logic. |
@Tool.register decorator to register Python functions as MCP tools:
Registering MCP tools
Registering MCP tools
MCP tool (custom Python function)
MCP tool (custom Python function)
Inline tool
Inline tool
Tool library tool
Tool library tool
Builder pattern
Builder pattern
LlmModel
from agenticai_core.designtime.models.llm_model import LlmModel, LlmModelConfig, LlmModelBuilder
Configures the language model for an agent or app.
LlmModel parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
model | str | Yes | Model identifier (for example, gpt-4o, claude-3-5-sonnet-20240620). |
provider | str | Yes | Provider name — Open AI, Anthropic, Azure OpenAI. |
connection_name | str | Yes | Platform connection name. |
max_timeout | str | No | Request timeout (for example, "60 Secs"). |
max_iterations | str | No | Maximum reasoning iterations (for example, "25"). |
modelConfig | LlmModelConfig | No | Generation parameter configuration. |
| Parameter | Type | Range | Description |
|---|---|---|---|
temperature | float | 0.0-2.0 | Response creativity. Lower values are more deterministic. |
max_tokens | int | — | Maximum tokens in the response. |
top_p | float | 0.0-1.0 | Nucleus sampling parameter. |
frequency_penalty | float | — | Penalizes repeated tokens (OpenAI). |
presence_penalty | float | — | Penalizes tokens already present in context (OpenAI). |
top_k | int | — | Top-K sampling (Anthropic-specific). |
| Range | Behavior |
|---|---|
| 0.0-0.3 | Deterministic. Use for factual or structured tasks. |
| 0.4-0.7 | Balanced. Good for most conversational tasks. |
| 0.8-1.5 | Creative. Use for generative or open-ended tasks. |
| 1.6-2.0 | Highly random. Experimental only. |
OpenAI
OpenAI
Anthropic
Anthropic
Azure OpenAI
Azure OpenAI
Builder pattern
Builder pattern
Prompt
from agenticai_core.designtime.models.prompt import Prompt
Defines the system instructions and behavioral rules for an agent.
Parameters:
| Parameter | Type | Description |
|---|---|---|
system | str | Base system prompt (for example, “You are a helpful assistant.”). |
custom | str | Custom instructions defining the agent’s specific role and behavior. |
instructions | list[str] | Additional rules or guidelines rendered as separate instruction blocks. |
custom and instructions:
| Variable | Description |
|---|---|
{{app_name}} | Application name. |
{{app_description}} | Application description. |
{{agent_name}} | Current agent name. |
{{memory.store_name.field}} | Value from a memory store field. |
{{session_id}} | Current session identifier. |
Basic prompt
Basic prompt
With instructions
With instructions
With memory context injection
With memory context injection
Orchestrator prompt
Orchestrator prompt
MemoryStore
from agenticai_core.designtime.models.memory_store import MemoryStore, Namespace, RetentionPolicy, Scope, RetentionPeriod, NamespaceType
Configures persistent data storage for your application. You access memory stores at runtime via the Memory runtime API.
MemoryStore parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | str | Yes | Display name. |
technical_name | str | Yes | Code identifier used to access the store at runtime. |
type | str | Yes | Store type — hotpath, persistent, global. |
description | str | No | Description of what the store contains. |
schema_definition | dict | Yes | JSON Schema defining the data structure. |
strict_schema | bool | No | If True, enforces schema validation. Recommended for production. |
namespaces | list[Namespace] | No | Data isolation identifiers. |
scope | Scope | Yes | Access control scope. |
retention_policy | RetentionPolicy | Yes | Data retention configuration. |
| Value | Description |
|---|---|
Scope.USER_SPECIFIC | Data unique to each user. Recommended for personal data. |
Scope.APPLICATION_WIDE | Data shared across all users. Use for global settings. |
Scope.SESSION_LEVEL | Temporary data cleared when the session ends. |
| Parameter | Type | Description |
|---|---|---|
name | str | Namespace identifier. |
type | NamespaceType | DYNAMIC (resolved at runtime) or STATIC (fixed value). |
value | str | Value or template (for example, "{user_id}"). |
description | str | Optional description. |
| Parameter | Type | Description |
|---|---|---|
type | RetentionPeriod | SESSION, DAY, WEEK, or MONTH. |
value | int | Number of periods to retain data (for example, 7 with DAY = 7 days). |
Session-scoped store
Session-scoped store
User-specific store
User-specific store
- Define clear, focused schemas. Use
strict_schema=Truein production. - Use
USER_SPECIFICfor personal data,APPLICATION_WIDEfor shared resources, andSESSION_LEVELfor temporary state. - Match
technical_nameto how you’ll reference the store in runtime code. - Choose retention policies based on data sensitivity and privacy requirements.
- Use
DYNAMICnamespaces to isolate data per user or session.
AppConfiguration
from agenticai_core.designtime.models.app_configuration import AppConfigurations, FillerMessages, FillerMessageMode, StaticConfig, DynamicConfig
Configures advanced app features such as streaming, file attachments, external agent integration, and filler messages.
AppConfigurations parameters:
| Parameter | Type | Description |
|---|---|---|
streaming | bool | Enables token-by-token streaming of LLM responses. |
attachments | dict | File upload settings — enabled, maxFileCount, maxFileSize (MB), maxTokens, supportedTypes. |
external_agent | dict | External agent integration — enabled, endpoint, timeout. |
filler_messages | FillerMessages | Messages shown to users while agents process requests. |
| Parameter | Type | Description |
|---|---|---|
enabled | bool | Enables filler messages. |
initial_delay | int | Delay in milliseconds before showing the first message. |
interval_duration | int | Interval in milliseconds between messages. |
max_message_count | int | Maximum number of messages to show. |
mode | FillerMessageMode | STATIC (pre-defined list) or DYNAMIC (AI-generated). |
static_config | StaticConfig | Required when mode=STATIC. List of {type, value} messages. |
dynamic_config | DynamicConfig | Required when mode=DYNAMIC. Specifies LLM and context window. |
Static filler messages
Static filler messages
Dynamic filler messages
Dynamic filler messages
AppNamespace
from agenticai_core.designtime.models.app_namespace import AppNamespace
Defines logical groupings for scoping app variables. Namespaces represent functional areas (for example, authentication, database), not environments — the platform resolves environment-specific variables automatically based on deployment context.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | str | Yes | Namespace identifier. Use lowercase with underscores. |
description | str | No | Description of the namespace’s purpose. |
development, production). Use functional names like authentication or database. The platform handles environment resolution automatically. Usage examples
Usage examples
AppVariable
from agenticai_core.designtime.models.app_variable import AppVariable
Defines environment variables accessible in tool code and agent configurations. Variables are scoped to namespaces.
Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
name | str | Yes | Variable name (for example, API_KEY). |
is_secured | bool | Yes | If True, the value is treated as a secret. |
value | str | Yes | Literal value or $env.VAR_NAME to reference an OS environment variable. |
hint | str | No | Description of what this variable is used for. |
namespaces | list[str] | No | Namespaces where this variable is available. Empty list means global. |
- Always set
is_secured=Truefor credentials, API keys, tokens, and passwords. - Use
$env.VAR_NAMEto reference OS environment variables rather than hardcoding secrets. - Use a
defaultnamespace for variables that apply broadly. - Set
namespaces=[]for truly global variables available everywhere.
Icon
from agenticai_core.designtime.models.icon import Icon
Defines visual identifiers for apps, agents, and tools.
Parameters:
| Parameter | Type | Description |
|---|---|---|
name | str | Icon identifier — for example, avatar1, logo18, calendar-check-01. |
color | str | Hex color (for example, #B2CCFF) or CSS gradient. |
type | str | human (avatar), logo (brand logo), or icon (action icon). |
| Type | Names |
|---|---|
human | avatar1, avatar2, avatar3 |
logo | logo1 through logo20 |
icon | calendar-check-01, briefcase-02, credit-card-02, microphone-01 |
Usage examples
Usage examples
Runtime APIs
Runtime APIs provide access to services available during request processing. Use them inside your tool functions and orchestrator methods. The diagram below shows how runtime services fit into the request flow. Message protocol flow:- The user sends a request via the Platform interface.
- The Platform (MCP Client) calls the SDK Orchestrator (MCP Server).
- The SDK Orchestrator receives a
MessageItemand returns aToolCall. - The Platform Agent executes based on the orchestrator’s routing.
- The Platform calls back to SDK tools, which use runtime services to process the request.
- Results flow back through the Platform to the user.
| Service | Import | Purpose |
|---|---|---|
RequestContext | agenticai_core.runtime.sessions.request_context | Access request info and get handles to other runtime services. |
EnvironmentVariables | Accessed via RequestContext | Read app variables configured at design-time. |
Memory | Accessed via RequestContext | Read and write persistent memory store data. |
Logger | agenticai_core.runtime.sessions.request_context | Structured logging with automatic session context. |
Tracer | agenticai_core.runtime.trace._langfuse_tracer | Distributed tracing via Langfuse. |
RequestContext
from agenticai_core.runtime.sessions.request_context import RequestContext
Provides access to request and session information and returns handles to all other runtime services. Always initialize RequestContext inside your tool or orchestrator method. Never initialize it at module level — it depends on active HTTP request headers that only exist during request processing.
| Property/Method | Returns | Description |
|---|---|---|
ctx.request_id | str | Unique identifier for the current request. |
ctx.context | dict | Request context data. Keys: userId, sessionId, appId. |
ctx.host | str | Platform host URL. |
ctx.get_memory() | MemoryManager | Returns a memory manager for all configured stores. |
ctx.get_memory_store_manager(name) | MemoryStoreManager | Returns an async context manager for a specific store. |
await ctx.get_environment_variables() | EnvironmentVariables | Returns an accessor for app variables. |
Usage example
Usage example
EnvironmentVariables
Accessed viaawait ctx.get_environment_variables().
Provides attribute-style access to app variables configured at design-time using AppVariable.
Access patterns:
| Pattern | Description |
|---|---|
env.VAR_NAME | Direct attribute access. Raises AttributeError if not found. |
env.get('VAR_NAME', default) | Safe access with a default value. |
'VAR_NAME' in env | Check if a variable exists. |
env.keys() | List all available variable names. |
Usage examples
Usage examples
Best practices
Best practices
- Call
get_environment_variables()once per tool invocation and reuse the result. - Use
env.get(name, default)for optional variables to avoidAttributeError. - Never log variables that contain
key,secret,password, ortokenin their names. Redact them in output.
Memory
Accessed viactx.get_memory() or ctx.get_memory_store_manager(name).
Provides read, write, and delete operations on memory stores configured at design-time with MemoryStore.
MemoryManager methods (from ctx.get_memory()):
| Method | Description |
|---|---|
await memory.get_content(store_name, projections) | Reads data from a store. projections is a dict of {field: 1} to include or {field: 0} to exclude. |
await memory.set_content(store_name, content) | Writes data to a store. |
await memory.delete_content(store_name) | Deletes all data from a store. |
ctx.get_memory_store_manager(name)):
An async context manager for operations on a single store.
| Method | Description |
|---|---|
await store.get(projections) | Reads data with optional projections. |
await store.set(content) | Writes data. |
await store.delete() | Deletes store data. |
Usage examples
Usage examples
Best practices
Best practices
- Use projections to fetch only the fields you need. Avoid
{}projections that return entire documents. - Always check
result.successbefore accessingresult.data. - Provide fallback values when memory is unavailable — don’t let memory failures break tool responses.
- Use
MemoryStoreManageras an async context manager for coordinated operations on a single store.
Logger
from agenticai_core.runtime.sessions.request_context import Logger
Provides structured logging with automatic session context (user ID, session ID) included in every log entry.
Constructor:
| Parameter | Description |
|---|---|
name | Logger name, typically the tool or component name. |
request_context | Optional. Pass a shared RequestContext instance to correlate logs with memory and environment operations. |
| Method | Level | When to use |
|---|---|---|
await logger.debug(message) | DEBUG | Detailed diagnostic info — variable values, entry/exit points. |
await logger.info(message) | INFO | Normal operation tracking — tool start, completion, successful operations. |
await logger.warning(message) | WARNING | Conditions that don’t prevent execution but need attention. |
await logger.error(message) | ERROR | Errors that prevent normal operation. |
Usage examples
Usage examples
Troubleshooting
Troubleshooting
Best practices
Best practices
- Use descriptive logger names:
Logger('UserAuthTool')notLogger('Tool'). - Include relevant context:
f"Processing payment: amount={amount}, user={user_id}". - Never log sensitive data. Sanitize or redact passwords, API keys, and tokens.
- Use DEBUG for diagnostics, INFO for normal operations, WARNING and ERROR for actionable issues.
Tracer
from agenticai_core.runtime.trace._langfuse_tracer import Tracer
Provides distributed tracing for tool and orchestrator execution using Langfuse integration. The @tracer.observe decorator wraps functions to automatically capture inputs, outputs, timing, and session context.
Configuration — Set in your .env files:
| Variable | Description |
|---|---|
LANGFUSE_PUBLIC_KEY | Langfuse public key. |
LANGFUSE_SECRET_KEY | Langfuse secret key. |
LANGFUSE_HOST | Langfuse server URL (for example, https://cloud.langfuse.com). |
TRACING_ENABLED | Set to true to enable tracing. |
| Parameter | Description |
|---|---|
span_name | Span identifier. Use Type:operation convention (for example, Tool:get_balance). |
kind | Span type — Tool, Agent, Orchestrator, or span. |
metadata | Optional dict of additional contextual attributes. |
| Prefix | Use for |
|---|---|
Tool: | Tool functions (for example, Tool:get_balance) |
Agent: | Agent handlers (for example, Agent:banking_assistant) |
Orchestrator: | Orchestrator methods (for example, Orchestrator:supervisor) |
Database: | Database operations |
API: | External API calls |
Usage examples
Usage examples
Troubleshooting
Troubleshooting
- Ensure tracing occurs within an MCP request context, not at module level.
- Verify
.envfiles are loaded before the tracer initializes.
- Reduce span volume — only trace business-critical operations.
- Avoid large objects in
metadata.
Best practices
Best practices
- Trace tools, agents, and orchestrators. Skip utility functions.
- Use descriptive
span_namevalues —Tool:validate_credit_cardnottool1. - Add
metadatathat helps diagnose failures — operation type, service name, feature flags. - Let the tracer capture exceptions automatically by re-raising them rather than swallowing.