Agent: core

1. Behavior and Context

In the jazzmine architecture, the Agent core is Stateless but Context-Aware. While it does not store history in its own instance, it uses the WorkingMemoryStore to maintain an exhaustive picture of the current session.

Key behavioral patterns include:

• The Orchestration Loop: The agent uses a "Think-Then-Act" iterative loop. It can generate multiple internal thoughts and execute multiple sandbox tasks in a single turn before finally speaking to the user.
• Security Gating: It implements a "Zero-Trust" model with mandatory Input and Output gates. Every user message is scanned for threats/policy violations before reasoning, and every agent response is scanned for hallucinations or leakage before being displayed.
• Structured Feedback: When tools are executed in the sandbox, the agent receives the results formatted as structured XML. It interprets this data to decide whether the task is complete or if further steps are required.
• Asynchronous Maintenance: Heavy operations like conversation summarization are pushed to background tasks so they do not impact the user's perceived latency.

2. Purpose

• Decision Making: Determining whether to call a tool, ask for missing information (Slots), request confirmation, or provide a direct answer.
• Component Synchronization: Coordinating the timing and data flow between the MessageEnhancer, FlowSelector, ToolOrchestrator, and Rust-based memory stores.
• Observability: Driving the TurnTelemetry system to record a complete "Flight Log" (TurnTrace) of every decision made during the turn.
• Safety Enforcement: Acting as the final arbiter of what data is allowed to enter the system and what information is allowed to leave.

3. High-Level API

The Agent is typically utilized through its chat() method.

Example: Processing a User Request

from jazzmine.core.agent import Agent

# Standard interaction
result = await agent.chat(
    user_id="user_v2_4821",
    conversation_id="session_abc_123",
    content="I need to refund my last order for the broken headphones."
)

if result.is_blocked:
    print(f"Safety Alert: {result.response}")
else:
    print(f"Agent: {result.response}")
    print(f"Trace ID for debugging: {result.trace_id}")

5. Detailed Functionality

chat(user_id, conversation_id, content, ...)

Functionality: The primary gateway. It orchestrates the 13-phase turn lifecycle.

Core Workflow:

1. Ingestion: Ensures the conversation exists and stores the raw user message.
2. Input Security Gate: Checks the raw input against the SecurityGuard. If blocked, it flags the message and returns early without calling the LLM.
3. Context Binding: Starts a turn_context using the AgentLogger. This binds the trace_id to the current execution thread so all logs are correlated.
4. Internal Processing: Delegates to _chat_inner for the heavy reasoning logic.

_chat_inner(...) [Internal]

Functionality: The "Logical Engine" of the turn. This method runs inside the logging context.

How it works:

• Phase 3-4 (Enhancement & Recall): Resolves pronouns and simultaneously recalls past episodes and jargon.
• Phase 5 (Flow Selection): Decides if the user's intent matches a known "Skill" (SOP).
• Phase 8 (Agent Loop): Calls _run_agent_loop to handle iterative reasoning and sandbox tasks.
• Phase 9 (Security Gate - Output): Once a final response is generated, it is passed through the SecurityGuard. If the response contains unsafe data, it is discarded and replaced with a "Block Message."
• Phase 11 (Telemetry): Crystallizes the TurnTelemetry into a persistent TurnTrace.

_run_agent_loop(...) [Internal]

Functionality: The iterative reasoning cycle. This is where the Agent "thinks" and "acts."

Mechanism:

1. Sends the current context (Memory + Tools + Flows) to the LLM.
2. Parses the output for <task> tags.
3. If a <task> is found:

• Delegates the task to the ToolOrchestrator (Sandbox).
• Appends the tool's XML result to the conversation context.
• Repeats the loop (up to max_task_calls_per_turn).

1. If no <task> is found:

• Extracts the text within <response> tags as the final answer.

drain()

Functionality: Ensures all background tasks (like memory summarization) finish before the application shuts down.

• Critical Usage: Always call await agent.drain() before closing your LLM client to prevent connection errors in the background worker threads.

6. Output Protocol (Tag Parsing)

The Agent core interprets specific XML-style tags emitted by the LLM to drive behavior:

7. Error Handling & Resiliency

Safety Blocks

If the SecurityGuard blocks a turn:

• The is_blocked flag in the AgentTurnResult is set to True.
• The real LLM response (if generated) is purged from the result.
• The message is not stored as an assistant message in the permanent store to prevent "Hallucination Infection" of the memory.

Orchestration Failures

• LLM Timeout: If the primary reasoning model stalls, the agent records the error in the telemetry and returns a graceful "I encountered an error" message to the user.
• Missing Sandbox: If the LLM requests a sandbox that isn't registered, the agent core intercepts this, appends an error to the context, and asks the LLM to try a different approach.

8. Remarks

• The Correlation ID: The agent uses the User Message ID as the trace_id for the entire turn. This creates a perfect 1:1 link between the message stored in the database and every log line generated in your ELK/Datadog stack.
• Contextual Trimming: During "Slot Collection" or "Confirmation" phases, the agent automatically omits the <available_sandboxes> block. This optimization saves hundreds of tokens per turn by not showing documentation the agent isn't allowed to use during those specific states.
• Background Summarization: The agent uses asyncio.create_task to trigger the ConversationSummarizer. These tasks are tracked in a weak set to ensure they aren't garbage collected before they complete.