Agent Loop Internals

​

Core Responsibilities

• Assembling the effective system prompt and tool schemas via prompt_builder.py
• Selecting the correct provider/API mode (chat_completions, codex_responses, anthropic_messages)
• Making interruptible model calls with cancellation support
• Executing tool calls (sequentially or concurrently via thread pool)
• Maintaining conversation history in OpenAI message format
• Handling compression, retries, and fallback model switching
• Tracking iteration budgets across parent and child agents
• Flushing persistent memory before context is lost

​

Two Entry Points

# Simple interface — returns final response string
response = agent.chat("Fix the bug in main.py")

# Full interface — returns dict with messages, metadata, usage stats
result = agent.run_conversation(
    user_message="Fix the bug in main.py",
    system_message=None,           # auto-built if omitted
    conversation_history=None,      # auto-loaded from session if omitted
    task_id="task_abc123"
)

​

API Modes

1. Explicit api_mode constructor arg (highest priority)
2. Provider-specific detection (e.g., anthropic provider → anthropic_messages)
3. Base URL heuristics (e.g., api.anthropic.com → anthropic_messages)
4. Default: chat_completions

​

Turn Lifecycle

run_conversation()
  1. Generate task_id if not provided
  2. Append user message to conversation history
  3. Build or reuse cached system prompt (prompt_builder.py)
  4. Check if preflight compression is needed (>50% context)
  5. Build API messages from conversation history
     - chat_completions: OpenAI format as-is
     - codex_responses: convert to Responses API input items
     - anthropic_messages: convert via anthropic_adapter.py
  6. Inject ephemeral prompt layers (budget warnings, context pressure)
  7. Apply prompt caching markers if on Anthropic
  8. Make interruptible API call (_interruptible_api_call)
  9. Parse response:
     - If tool_calls: execute them, append results, loop back to step 5
     - If text response: persist session, flush memory if needed, return

​

Message Format

{"role": "system", "content": "..."}
{"role": "user", "content": "..."}
{"role": "assistant", "content": "...", "tool_calls": [...]}
{"role": "tool", "tool_call_id": "...", "content": "..."}

​

Message Alternation Rules

• After the system message: User → Assistant → User → Assistant → ...
• During tool calling: Assistant (with tool_calls) → Tool → Tool → ... → Assistant
• Never two assistant messages in a row
• Never two user messages in a row
• Only tool role can have consecutive entries (parallel tool results)

​

Interruptible API Calls

┌────────────────────────────────────────────────────┐
│  Main thread                  API thread           │
│                                                    │
│   wait on:                     HTTP POST           │
│    - response ready     ───▶   to provider         │
│    - interrupt event                               │
│    - timeout                                       │
└────────────────────────────────────────────────────┘

• The API thread is abandoned (response discarded)
• The agent can process the new input or shut down cleanly
• No partial response is injected into conversation history

​

Tool Execution

​

Sequential vs Concurrent

• Single tool call → executed directly in the main thread
• Multiple tool calls → executed concurrently via ThreadPoolExecutor
  • Exception: tools marked as interactive (e.g., clarify) force sequential execution
  • Results are reinserted in the original tool call order regardless of completion order

​

Execution Flow

for each tool_call in response.tool_calls:
    1. Resolve handler from tools/registry.py
    2. Fire pre_tool_call plugin hook
    3. Check if dangerous command (tools/approval.py)
       - If dangerous: invoke approval_callback, wait for user
    4. Execute handler with args + task_id
    5. Fire post_tool_call plugin hook
    6. Append {"role": "tool", "content": result} to history

​

Agent-Level Tools

​

Callback Surfaces

​

Budget and Fallback Behavior

​

Iteration Budget

• Default: 500 iterations (configurable via agent.max_turns)
• Each agent gets its own budget. Subagents get independent budgets capped at delegation.max_iterations (default 50) — total iterations across parent + subagents can exceed the parent’s cap
• At 100%, the agent stops and returns a summary of work done

​

Fallback Model

1. Check fallback_providers list in config
2. Try each fallback in order
3. On success, continue the conversation with the new provider
4. On 401/403, attempt credential refresh before failing over
5. A Codex Responses turn that stalls on reasoning-only output (three consecutive continuations with no visible text or tool call) also fails over to the next fallback with reason incomplete_response; if the stall consumed the iteration budget, the fallback gets exactly one bounded grace call

​

Compression and Persistence

​

When Compression Triggers

• Preflight (before API call): If conversation exceeds 50% of model’s context window
• Gateway auto-compression: If conversation exceeds 85% (more aggressive, runs between turns)

​

What Happens During Compression

1. Memory is flushed to disk first (preventing data loss)
2. Middle conversation turns are summarized into a compact summary
3. The last N messages are preserved intact (compression.protect_last_n, default: 20)
4. Tool call/result message pairs are kept together (never split)
5. A new session lineage ID is generated (compression creates a “child” session)

​

Session Persistence

• Messages are saved to the session store (SQLite via mibyan_state.py)
• Memory changes are flushed to MEMORY.md / USER.md
• The session can be resumed later via /resume or mibyan chat --resume

​

Key Source Files

​

Related Docs

• Provider Runtime Resolution
• Prompt Assembly
• Context Compression & Prompt Caching
• Tools Runtime
• Architecture Overview