Query Loop Implementation

Query Loop Implementation

Core Idea

Build the loop as product infrastructure, not prompt glue:

ConversationManager -> QueryLoop -> ToolRuntime

• ConversationManager owns durable state: session id, messages, user settings, budget, persistence.
• QueryLoop owns one task turn: call model, detect tool calls, execute tools, append tool results, repeat.
• ToolRuntime owns registered tools: schemas, permission checks, execution, error formatting.

Use ReAct as the mental model:

Thought -> Action -> Observation -> Thought -> Answer

Implement it as structured API traffic:

model thinking/text -> tool_call -> tool_result -> next model call -> final text

Implementation Workflow

1. Inspect the user's stack and current LLM call site.

Find where messages are built, where the model is called, and whether tool/function calling is already configured.

1. Introduce a minimal query loop.

Keep the first version narrow: one model call function, one tool registry, explicit exit conditions.

1. Normalize message shapes.

Use the provider's structured tool-call format when available. Avoid parsing free-form Action: text unless the provider has no function/tool-calling API.

1. Add tool execution safety.

Validate tool input against a schema, apply permission checks for risky tools, wrap failures as tool results, and log every call.

1. Add exit and budget guards before expanding features.

Always include maxTurns, timeout/cancel support, token/cost budget checks, and a fatal-error path.

1. Keep context-window strategy outside this skill.

Accept messages as loop input and return updated messages, but leave trimming, retrieval, summarization, and compaction to a separate context-management layer.

Minimal Loop

Adapt this shape to the user's language and SDK:

async function runQueryLoop({
  initialMessages,
  model,
  tools,
  maxTurns = 10,
  signal,
}: {
  initialMessages: Message[]
  model: ModelClient
  tools: ToolRegistry
  maxTurns?: number
  signal?: AbortSignal
}) {
  let messages = [...initialMessages]

  for (let turn = 1; turn 
  call(input: ValidatedInput, ctx: ToolContext): Promise
}

Execution order:

find tool by name
-> schema validate model input
-> run tool-specific validation
-> check permission
-> call tool
-> format success or error as tool_result

Return tool errors to the model when it can plausibly recover, for example invalid arguments, file not found, empty search result, or transient API errors. Stop the loop for security violations, repeated failures, missing credentials, or budget exhaustion.

Product Design Guidance

Keep "intelligence" in the model and "reliability" in code:

• Let the model decide whether it needs another tool call.
• Let code enforce schemas, permissions, budgets, and loop exits.
• Keep prompts focused on tool semantics and task policy.
• Keep implementation focused on deterministic control flow.

For simple AI apps, avoid subagents, worktrees, and streaming tool execution at first. Add them only when the product actually needs parallel work, isolation, or long-running tasks.

When More Detail Is Needed

Read references/query-loop-patterns.md when designing a new query engine, reviewing an existing implementation, or explaining ReAct-to-query-loop architecture to another engineer.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: simbajigege
• Source: simbajigege/book2skills
• License: MIT
• Homepage: https://book2skills.com/

Install and usage instructions live in the source repository linked above.