Skip to content
Docs

Documentation navigation

Session Config Models

Typed invocation config objects for memory, system tools, orchestration, structured output, and swarm transport.

#Session Config Models

Public configuration models, including active invocation controls and retained compatibility schemas. The sections below distinguish the two.

Use these objects to set controls, not control keys in request metadata.

#Import

Python 
from maivn import (
    MemoryAssetsConfig,
    MemoryConfig,
    MemoryInsightExtractionConfig,
    MemoryGraphExtractionConfig,
    MemoryResourceConfig,
    MemoryRetrievalConfig,
    MemorySkillConfig,
    MemorySkillExtractionConfig,
    SessionExecutionConfig,
    SessionOrchestrationConfig,
    StructuredOutputConfig,
    SwarmAgentConfig,
    SwarmConfig,
    SystemToolsConfig,
)

Agent(...) and Swarm(...) accept memory, system-tool, and orchestration config objects or equivalent dictionaries for scope defaults and invocation overrides. Not every exported model is an invocation argument, and orchestration settings are retained locally without changing runtime behavior.

Python 
from maivn import Agent, SystemToolsConfig
from maivn.messages import HumanMessage

agent = Agent(
    name="analyst",
    api_key="...",
    system_tools_config=SystemToolsConfig(allowed_tools=["web_search"]),
)

response = agent.invoke(
    [HumanMessage(content="Research this topic")],
    system_tools_config=SystemToolsConfig(allowed_tools=["web_search", "repl"]),
)

#Configuration Layers

LayerWhereMerge behavior
Scope defaultAgent(...), Swarm(...)Applied to every call from that scope
Invocation overrideinvoke(), stream(), ainvoke(), astream()Merged over scope defaults for one call
Compiled toolscompile_tools()Produces current model-visible ToolMetadata schemas

Invocation metadata is accepted but ignored by the current Agent and Swarm methods. It does not carry labels or runtime controls to the server. Use supported typed arguments for invocation behavior and application logging for your own labels.

#SystemToolsConfig

Controls which system tools are available to a run.

Plain text 
SystemToolsConfig(
    allowed_tools: list[str] | None = None,
    allow_private_data: bool | None = None,
    allow_private_data_placeholders: bool | None = None,
)
FieldTypeDefaultDescription
allowed_toolslist[str] | NoneNoneSystem tool allowlist. Use [] to disable all system tools for the call.
allow_private_databool | NoneNoneAllow system tools to receive raw private_data values. Advanced use only.
allow_private_data_placeholdersbool | NoneNoneAllow system tools to receive private-data placeholders. The SDK enables this by default when resolving invocation config.
Python 
agent.invoke(
    messages,
    system_tools_config=SystemToolsConfig(
        allowed_tools=["web_search", "repl"],
    ),
)

#SessionOrchestrationConfig

Retained compatibility model for orchestration settings. The current v2 invocation contract does not accept orchestration_config: the SDK retains these values locally but does not send them to the runtime. They do not change server loop behavior or impose a cycle limit. The fields below describe the compatibility schema, not active server controls.

Plain text 
SessionOrchestrationConfig(
    mode: Literal[
        "single_shot_dag",
        "supervisor_loop",
        "strict_user_dag",
        "hybrid",
    ] | None = None,
    final_output_mode: Literal[
        "terminal",
        "supervised",
        "aggregator_only",
    ] | None = None,
    allow_followup_actions: bool | None = None,
    stop_strategy: Literal[
        "orchestrator_decides",
        "final_tool_completed",
        "objective_satisfied",
        "max_cycles",
        "blocker_detected",
    ] | None = None,
    allow_reevaluate_loop: bool | None = None,
    max_cycles: int | None = None,
)

The model validates the following fields and keeps them available for source compatibility: mode, final_output_mode, allow_followup_actions, stop_strategy, allow_reevaluate_loop, and max_cycles. max_cycles, when provided, must be greater than zero.

Do not use these fields to promise supervised follow-up work, an objective-based stop condition, or a caller-selected cycle limit. Use explicit dependencies, @depends_on_reevaluate, final-tool selection, and application-side retry or verification loops for behavior that must work with the current SDK.

#MemoryConfig

Controls retrieval and persistence. Several accepted compatibility fields are not forwarded by the current SDK: summarization_enabled, retrieval.candidate_limit, retrieval.insight_relevance_floor, extraction sharing_scope, skill_extraction.confidence_threshold, and insight_extraction.min_relevance_score. Setting them does not change the run. top_k supplies the default count for skills, insights, and resources when their individual injection counts are omitted. Nested per-call configs replace the corresponding nested scope config; they are not merged field by field.

Plain text 
MemoryConfig(
    enabled: bool | None = None,
    level: Literal["none", "glimpse", "focus", "clarity"] | None = None,
    summarization_enabled: bool | None = None,
    persistence_mode: Literal[
        "persist_none",
        "vector_only",
        "vector_plus_graph",
    ] | None = None,
    retrieval: MemoryRetrievalConfig | None = None,
    skill_extraction: MemorySkillExtractionConfig | None = None,
    insight_extraction: MemoryInsightExtractionConfig | None = None,
    graph_extraction: MemoryGraphExtractionConfig | None = None,
)
FieldTypeDefaultDescription
enabledbool | NoneNonePublic memory master toggle for the invocation.
level"none" | "glimpse" | "focus" | "clarity" | NoneNoneMemory behavior level.
summarization_enabledbool | NoneNoneCompatibility value; not forwarded.
persistence_mode"persist_none" | "vector_only" | "vector_plus_graph" | NoneNoneOptional persistence downscope.
retrievalMemoryRetrievalConfig | NoneNoneRetrieval limits and signal toggles.
skill_extractionMemorySkillExtractionConfig | NoneNoneSkill extraction controls.
insight_extractionMemoryInsightExtractionConfig | NoneNoneInsight extraction controls.
Plain text 
MemoryRetrievalConfig(
    top_k: int | None = None,
    candidate_limit: int | None = None,
    skills_enabled: bool | None = None,
    insights_enabled: bool | None = None,
    resources_enabled: bool | None = None,
    graph_enabled: bool | None = None,
    graph_injection_max_count: int | None = None,
    skill_injection_max_count: int | None = None,
    insight_injection_max_count: int | None = None,
    resource_injection_max_count: int | None = None,
    insight_relevance_floor: float | None = None,
)
Retrieval fieldTypeValidation
top_kint | None>= 1
candidate_limitint | None>= 1; no cross-field check; not forwarded
skills_enabledbool | NoneOptional skill recall toggle
insights_enabledbool | NoneOptional insight recall toggle
resources_enabledbool | NoneOptional resource recall toggle
skill_injection_max_countint | None>= 1
insight_injection_max_countint | None>= 1
resource_injection_max_countint | None>= 1
insight_relevance_floorfloat | None0.0 to 1.0
Plain text 
MemorySkillExtractionConfig(
    enabled: bool | None = None,
    sharing_scope: Literal["agent", "swarm", "project", "org"] | None = None,
    confidence_threshold: float | None = None,
    max_count: int | None = None,
)

MemoryInsightExtractionConfig(
    enabled: bool | None = None,
    sharing_scope: Literal["agent", "swarm"] | None = None,
    max_count: int | None = None,
    min_relevance_score: float | None = None,
)

MemoryGraphExtractionConfig(enabled=None, max_count=None) controls graph extraction; max_count accepts 1 through 16. Retrieval also accepts graph_enabled and graph_injection_max_count (1 through 16). Graph persistence requires persistence_mode="vector_plus_graph".

The extraction sharing_scope fields are validated compatibility values but are not sent by the SDK. For broader reuse, use Portal promotion or client.memory.insights.promote(memory_id, target_scope="project").

#MemoryAssetsConfig

Compatibility schema for user-defined skills and bound resources. For current invocations, supply skills=[...] and resources=[...] on Agent or Swarm; the SDK prepares those assets through its resource path. It does not construct or send a MemoryAssetsConfig object as an invocation field.

Plain text 
MemoryAssetsConfig(
    defined_skills: list[MemorySkillConfig] = [],
    bound_resources: list[MemoryResourceConfig] = [],
    recall_turn_active: bool | None = None,
)
FieldTypeDefaultDescription
defined_skillslist[MemorySkillConfig][]User-defined skill payloads available for retrieval.
bound_resourceslist[MemoryResourceConfig][]Bound resource payloads available for retrieval.
recall_turn_activebool | NoneNoneMarks a recall-active turn for server-managed memory behavior.

#MemorySkillConfig

Plain text 
MemorySkillConfig(
    skill_id: str | None = None,
    id: str | None = None,
    name: str | None = None,
    title: str | None = None,
    description: str | None = None,
    content: str | None = None,
    steps: list[dict[str, Any]] = [],
    preconditions: dict[str, Any] = {},
    postconditions: dict[str, Any] = {},
    sharing_scope: Literal["agent", "swarm", "project", "org"] | None = None,
    origin: str | None = None,
    confidence: float | None = None,
    metadata: dict[str, Any] = {},
    agent_id: str | None = None,
    swarm_id: str | None = None,
)

MemorySkillConfig accepts an empty model; it does not require a name or title. confidence, when set, must be between 0.0 and 1.0. For current constructor skill entries and registration, use Skill, not this compatibility model; see SDK Resource Configuration.

#MemoryResourceConfig

Plain text 
MemoryResourceConfig(
    resource_id: str | None = None,
    id: str | None = None,
    title: str | None = None,
    name: str | None = None,
    description: str | None = None,
    content: str | None = None,
    source_url: str | None = None,
    url: str | None = None,
    content_base64: str | None = None,
    mime_type: str | None = None,
    tags: list[str] = [],
    binding_type: str | None = None,
    sharing_scope: Literal["agent", "swarm", "project", "org"] | None = None,
    source_type: str | None = None,
    agent_id: str | None = None,
    swarm_id: str | None = None,
)

MemoryResourceConfig accepts an empty model. It is not accepted directly in constructor resources; use a dictionary with text_content or file, name, and mime_type. See SDK Resource Configuration.

For replacement uploads, use client.resources.upload with bytes and ResourceUploadOptions(resource_id=...). Setting fields on this compatibility model does not upload or replace a resource.

#SwarmConfig

Retained compatibility schema for swarm metadata. Configure Swarm(...) and member Agent(...) instances for current invocations. The SDK builds their runtime definitions directly; it does not construct or send this model.

Plain text 
SwarmConfig(
    invocation_intent: bool | None = None,
    swarm_id: str | None = None,
    swarm_name: str | None = None,
    swarm_description: str | None = None,
    swarm_system_prompt: str | None = None,
    agent_roster: list[SwarmAgentConfig] = [],
    agent_invocation_tool_map: dict[str, str] = {},
    agent_invocation: bool | None = None,
    use_as_final_output: bool | None = None,
    invoked_agent_id: str | None = None,
    invoked_agent_name: str | None = None,
    included_nested_synthesis: Literal["auto", True, False] | None = None,
    sdk_delivery_mode: str | None = None,
    agent_dependency_context: dict[str, Any] | None = None,
    agent_dependency_context_keys: list[str] | None = None,
)
FieldTypeDescription
invocation_intentbool | NoneMarks the request as a swarm invocation.
swarm_id, swarm_name, swarm_description, swarm_system_promptstr | NoneSwarm identity and prompt context.
agent_rosterlist[SwarmAgentConfig]Typed member roster sent to the server.
agent_invocation_tool_mapdict[str, str]Maps generated member invocation tool IDs to agent IDs.
agent_invocationbool | NoneMarks a nested agent invocation.
use_as_final_outputbool | NoneMarks whether the invoked member should produce the final output.
invoked_agent_id, invoked_agent_namestr | NoneNested member identity.
included_nested_synthesis"auto" | True | False | NoneNested synthesis mode for member invocations.
sdk_delivery_modestr | NoneSDK transport mode used by server routing.
agent_dependency_contextdict[str, Any] | NoneDependency payload for nested agent execution.
agent_dependency_context_keyslist[str] | NoneDependency context key list for nested execution.

#SwarmAgentConfig

Plain text 
SwarmAgentConfig(
    agent_id: str | None = None,
    name: str | None = None,
    description: str | None = None,
    use_as_final_output: bool = False,
    included_nested_synthesis: Literal["auto", True, False] | None = None,
    included_nested_synthesis_guidance: str | None = None,
    has_final_tool: bool = False,
    invocation_tool_id: str | None = None,
    invokes_via_dependency: list[str] = [],
    memory_config: MemoryConfig | None = None,
    memory_defined_skills: list[MemorySkillConfig] = [],
    memory_bound_resources: list[MemoryResourceConfig] = [],
)

#StructuredOutputConfig

Retained compatibility schema for structured-output metadata. Current code uses agent.structured_output(Model).invoke(...) or agent.invoke(..., structured_output=Model). Those paths compile a final tool and send the output schema; they do not construct or send this model.

Plain text 
StructuredOutputConfig(
    enabled: bool | None = None,
    model: str | None = None,
)
FieldTypeDefaultDescription
enabledbool | NoneNoneWhether structured-output routing is requested.
modelstr | NoneNoneStructured-output model name recorded for server routing and observability.

#SessionExecutionConfig

Retained compatibility schema for execution metadata. The current SDK does not construct or send this model during invocation. Its timeout field does not set an execution deadline or configure the HTTP client. Use Client(http_timeout=...) or per-call RunOptions(timeout=...) for HTTP timeouts.

Plain text 
SessionExecutionConfig(
    agent_id: str | None = None,
    timeout: int | float | None = None,
    sdk_delivery_mode: str | None = None,
    client_timezone: str | None = None,
    sdk_deployment_timezone: str | None = None,
)
FieldTypeDefaultDescription
agent_idstr | NoneNoneSDK agent identifier.
timeoutint | float | NoneNoneRetained non-negative value; not an active timeout control.
sdk_delivery_modestr | NoneNoneSDK delivery mode used by server routing.
client_timezonestr | NoneNoneClient IANA timezone used for datetime-aware execution.
sdk_deployment_timezonestr | NoneNoneSDK deployment timezone fallback.

#Metadata Boundary

Agent and Swarm accept invocation metadata for compatibility but do not send it to the server. Runtime controls placed there have no effect. Use supported arguments directly:

Python 
agent.invoke(messages, system_tools_config={"allowed_tools": ["web_search"]})

#See Also