AssistantConfig & Profile

AssistantConfig

The top-level model for an agent. Stored in the registry and loaded at inference time.

class AssistantConfig(BaseModel, SecretsAware):
    assistant_id: str
    nickname: str | None = None          # max 64 chars
    description: str | None = None       # max 3000 chars
    tags: list[str] | None = None
    channels: list[Channels] | None = None
    shields: dict[str, Shields] | None = None
    empathy: EmpathyEngine | None = None
    response: EmpathyProfile             # required

All fields use extra="forbid" — unknown fields raise ValidationError at load time.

Loading from the registry

from alquimia.core import get_assistant_config
from alquimia.registry.registry import AlquimiaRegistry

registry = AlquimiaRegistry()
registry.load({"agentspace_id": "default"})
config = get_assistant_config(registry, "my-agent")

Loading from a dict

from alquimia.core.profile import AssistantConfig

config = AssistantConfig.model_validate(
    my_dict,
    context={"registry": registry, "assistant_id": "my-agent"},
)

The context parameter is required for secret resolution and A2A agent discovery.

Profile

The runtime behavior specification for an agent.

class Profile(BaseModel):
    system_prompt: str | None = None
    prompt_clauses: dict[str, str] | None = None
    knowledge_base: list[KnowledgeBases] | None = None
    runtime_context: RuntimeContext = Field(default_factory=RuntimeContext)
    short_term_memory_strategy: list[ShortTermMemoryStrategy] | None = None
    long_term_memory_strategy: list[LongTermMemoryStrategy] | None = None
    evaluation_strategy: EvaluationStrategy = Field(
        default_factory=OneShootEvaluationStrategy
    )
    tools: list[ToolConfig] | None = None
    persistence_strategy: ContextPersistenceStrategyType = "INCREMENTAL"

`format_system_message(**kwargs)`

Renders the system prompt Jinja2 template with the provided context.

system_msg = profile.format_system_message(
    rag_context=["Paris is the capital of France."],
    language="English",
)

Automatically injects:

rag_context — RAG retrieval results
attachment_context — uploaded file content
evaluation_strategy.prompt_clauses — strategy instructions
prompt_clauses — custom named sections
runtime_context.prompt_clauses — dynamic state (plan, condensed context)

ResponseProfile

Wraps a Profile and its LLM connector config.

class ResponseProfile(BaseModel):
    provider_id: Literal["alquimia"]
    profile: Profile | None = None
    config: GenerativeResponseConnector | None = None

RuntimeContext

Mutable per-inference state injected into the system prompt.

class RuntimeContext(BaseModel):
    plan_content: str | None = None
    condensed_context: str | None = None

prompt_clauses is a computed property that returns non-null fields as a dict:

context = RuntimeContext(plan_content="1. Search\n2. Summarize")
context.prompt_clauses
# {"Current plan": "1. Search\n2. Summarize"}

ContextPersistenceStrategy

Controls how the conversation is saved after inference.

Value	Behavior
`INCREMENTAL`	Append new messages to the existing session
`FLUSH`	Replace the session with the current conversation
`EPHEMERAL`	Do not persist

EmpathyEngine

Evaluates rules against context and returns a modified profile on the first match.

class EmpathyEngine(BaseModel):
    rules: list[EmpathyRule]

    def evaluate_context(
        self,
        context: dict[str, Any],
        main_profile: EmpathyProfile,
    ) -> EmpathyProfile | None: ...

EmpathyRule strategies

Strategy	Class	Behavior
`none`	`NoneEmpathyRule`	Match but return the main profile unchanged
`override`	`OverrideEmpathyRule`	Replace the entire profile with `response`
`merge`	`MergeEmpathyRule`	Deep-merge `response` into the main profile

Rule fields

Field	Type	Description
`rule_id`	`string`	Unique identifier (auto-generated if omitted)
`strategy`	`string`	`none`, `override`, or `merge`
`description`	`string`	Human-readable description
`conditions`	`string[]`	`simpleeval` expressions evaluated against context
`requirements`	`string[]`	Context keys that must be present for the rule to run
`response`	`EmpathyProfile`	The profile to apply on match

Conditions use simpleeval.EvalWithCompoundTypes — never bare eval().

Agent Configuration — full JSON examples
Evaluation Strategies — how the LLM is called
Memory Strategies — short-term and long-term memory

AssistantConfig & Profile