Agent Types

The types module defines the static configurations and return structures for the jazzmine Agent. It acts as the "Contract of Engagement," defining the operational limits of an agent instance and the exact shape of the data returned to the calling application after every conversational turn.

Behavior and Context

In the jazzmine lifecycle, these types are used at the very boundaries of the system:

Initialization: AgentConfig is passed to the factory to set up the agent's identity and resource constraints.
Response: AgentTurnResult is the final object returned by Agent.chat(), containing the response text and the pointers needed for auditing.

Purpose

Operational Constraints: Defining hard caps on tool calls and memory recall to prevent runaway costs or context window overflow.
Identity Persistence: Managing the agent_id used for multi-tenant database lookups.
Security Feedback: Providing a specific flag (is_blocked) to alert the UI if a message was intercepted by safety filters.

Class: AgentConfig (Dataclass)

Purpose: Defines the static personality and operational policy of an agent instance.

Attribute	Type	Default	Description
name	str	Required	The display name used in the system prompt.
personality	str	Required	High-level instructions on tone, style, and expertise.
agent_id	str	Required	Stable ID used for memory retrieval in Rust cores.
has_tools	bool	True	If False, the agent uses a simplified "Chat-only" prompt.
default_sandbox_name	str	"default"	Sandbox used if a <task> tag omits the attribute.
default_execution_mode	ExecutionMode	PLAN	The strategy for tool execution (PLAN or INTERACTIVE).
max_task_calls_per_turn	int	8	Max number of tool-call loops allowed per message.
max_interactive_steps	int	10	Max steps allowed in a single interactive sandbox task.
episodic_same_conv_limit	int	3	Max past summaries from the current thread to recall.
episodic_prev_conv_limit	int	2	Max summaries from other threads to recall.
semantic_top_k	int	8	Max domain jargon definitions to show the agent.

Class: AgentTurnResult (Dataclass)

Purpose: The structured outcome of a single Agent.chat() invocation.

Attribute	Type	Description
response	str	The clean text response to be displayed to the end-user.
message_id	str	The unique ID of the assistant message in the MessageStore.
trace_id	str	The ID of the TurnTrace record used for deep auditing.
invoked_flows	list[str]	Names of the skills (Flows) that were active during this turn.
invoked_tools	list[str]	Names of the sandbox tasks performed during this turn.
errors	list[str]	Non-fatal warnings encountered (e.g., "memory_recall_failed").
turn_number	int	The current position in the conversation history.
is_blocked	bool	True if the SecurityGuard prevented the turn from completing.

Usage Example

from jazzmine.core.agent import AgentConfig, AgentTurnResult
from jazzmine.core.tools import ExecutionMode

# 1. Configuration
config = AgentConfig(
    name="Aria",
    personality="A helpful assistant for technical support.",
    agent_id="support_bot_v1",
    max_task_calls_per_turn=4,
    default_execution_mode=ExecutionMode.INTERACTIVE
)

# 2. Handling a result (returned from agent.chat)
def handle_response(result: AgentTurnResult):
    if result.is_blocked:
        print("Safety Warning: Response blocked.")
    else:
        print(f"[{result.turn_number}] {result.response}")
        print(f"Trace for Audit: {result.trace_id}")

Behavior and Context

Purpose

Class: AgentConfig (Dataclass)

Class: AgentTurnResult (Dataclass)

Usage Example

On this page