Jazzmine

Agent: types

1. 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.

2. 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.

3. 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.

4. 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.

5. Usage Example

python

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}")