BoxAgnts Introduction (6) — Agent Multi-Turn Conversation and Tool/Skill Invocation

BoxAgnts implements a multi-turn agent conversation system that requires three API calls and two tool executions to complete a single user request, such as reading a config file and changing a port number. The system supports three pre-installed agent roles—build, plan, and explore—each with different permission levels and prompt characteristics that can override model selection and maximum turn limits. The core `run_query_loop()` function manages conversation history, tool execution within WASM sandboxes, streaming push, and context management across multiple API interactions.

If you've only chatted with ChatGPT, you might think an AI Agent is simply "send a prompt to the API, display the response." The reality is far more complex. Here is a complete Agent interaction flow in BoxAgnts: User input: "Help me read config.toml and change port to 9090" 1. User message added to conversation history 2. Build system prompt tool list + skill list + AGENTS.md + Agent role definition 3. Call LLM API → stream receive response 4. AI decides to call tool: tool use "read", {path: "config.toml"} 5. Execute read tool within WASM sandbox 6. Tool result injected into conversation history 7. Call API again → AI analyzes config 8. AI decides to call tool: tool use "edit", {path: "config.toml", old: "port = 8080", new: "port = 9090"} 9. Execute edit tool 10. Tool result injected into conversation 11. Call API again → AI responds: "Port has been changed from 8080 to 9090" 12. end turn → Conversation ends This process involves 3 API calls, 2 tool executions, streaming push, and context management. This article dissects the design and implementation of each link. Before starting the reasoning loop, the Agent's "role" needs to be defined. BoxAgnts comes with three pre-installed Agents: // boxagnts-workspace/src/config.rs pub struct AgentDefinition { pub description: "Option<String , // Description" pub model: Option<String , // Model override pub temperature: Option<f64 , // Temperature override pub prompt: Option<String , // System prompt prefix pub access: String, // Permission: full / read-only / search-only pub visible: bool, // Whether visible in @agent autocomplete pub max turns: Option<u32 , // Max turns override pub color: Option<String , // Terminal display color } The three pre-installed Agent roles: | Agent | Permission | Prompt Characteristics | Use Cases | |---|---|---|---| build | full | "You are the build agent. Focus on implementing..." | Coding, modifying files | plan | read-only | "You are the plan agent. You can read files and analyze..." | Code analysis, architecture design | explore | search-only | "Fast search-only agent for code exploration" | Quick search, file location | The prompt field in the Agent definition is injected at the very front of the system prompt when the query loop starts: js // boxagnts-query/src/query.rs if let Some ref agent = config.agent definition { if let Some ref agent prompt = agent.prompt { patched.system prompt = Some match &config.system prompt { Some existing = format "{}\n\n{}", agent prompt, existing , None = agent prompt.clone , } ; } } Additionally, the Agent can override the model and max turns: js let effective model = if let Some ref agent = config.agent definition { agent.model.clone .unwrap or else || config.model.clone } else { config.model.clone }; let effective max turns = config.agent definition .as ref .and then |a| a.max turns .unwrap or config.max turns ; This means users can use Agent definitions to implement "different models and roles at different stages of the same session" — for example, using a read-only slow-thinking model during the planning phase and a full-access fast model during the execution phase. run query loop is the most core function in BoxAgnts, located in the boxagnts-query crate: pub async fn run query loop client: &AnthropicClient, // API client messages: &mut Vec<Message , // Conversation history mutable reference tools: & Box<dyn Tool , // Tool collection tool ctx: &ToolContext, // Tool execution context config: &QueryConfig, // Loop configuration cost tracker: Arc<CostTracker , // Cost tracking event tx: Option<mpsc::UnboundedSender<QueryEvent , // Event push cancel token: CancellationToken, // Cancellation signal pending messages: Option<&mut Vec<String , // Pending message queue - QueryOutcome This function signature is itself an architectural document. Each parameter is a design decision: | Parameter | Design Intent | |---|---| client | Single entry point, but internally switches 20+ models via ProviderRegistry | messages: &mut Vec<Message | Directly modifies conversation history, appends content each iteration | tools: & Box<dyn Tool | Type-erased tool collection, AI calls by name | tool ctx | Carries work dir, allowed hosts and other sandbox config | event tx | Real-time push of per-turn status to Dashboard / TUI | cancel token | User can interrupt loop at any time | pending messages | Insert commands mid-execution e.g., user sends new message during tool execution | ┌─────────────────────────────────────────────┐ │ loop { │ │ │ │ ① Check termination conditions │ │ · turn max turns ? → EndTurn │ │ · cancel token ? → Cancelled │ │ · budget exceeded? → BudgetExceeded │ │ │ │ ② Preprocess messages │ │ · drain pending messages queue │ │ · apply tool result budget truncate old results │ │ · auto compact context compression │ │ │ │ ③ Build system prompt + Call LLM API │ │ · Inject Agent definition / AGENTS.md │ │ · Build CreateMessageRequest │ │ · Stream receive StreamEvent │ │ · Accumulate text / thinking / tool use blocks │ │ │ │ ④ Process response │ │ · end turn → return │ │ · tool use → parallel execute tools → inject results → continue │ │ · max tokens → resume conversation → continue │ │ │ │ ⑤ Error recovery │ │ · overloaded → switch fallback model │ │ · stream stall → retry max 2 times │ │ │ │ } │ └─────────────────────────────────────────────┘ Before each API call, BoxAgnts builds a complete system prompt: php fn build system prompt config: &QueryConfig - SystemPrompt { let opts = SystemPromptOptions { custom system prompt: config.system prompt.clone , // User custom append system prompt: config.append system prompt.clone , // Appended content output style: config.output style, // Output style custom output style prompt: config.output style prompt.clone , working directory: config.working directory.clone , // Current working directory ..Default::default }; let text = boxagnts core::system prompt::build system prompt &opts ; SystemPrompt::Text text } The system prompt structure is hierarchical: ┌──────────────────────────────────────┐ │ Agent Role Definition build/plan/explore │ ← AgentDefinition.prompt ├──────────────────────────────────────┤ │ Core Capability Declaration │ │ · Available tool list 16+ │ ← Dynamically generated from tools parameter │ · Skill list │ ← Discovered by SkillTool │ · Output format requirements │ │ · Security boundaries │ ├──────────────────────────────────────┤ │ AGENTS.md content │ ← User project-level behavior spec ├──────────────────────────────────────┤ │ Dynamic Boundary Marker │ │ --- Above cached, below not cached ---│ ├──────────────────────────────────────┤ │ Session-specific information │ ← Current working directory, time, etc. └──────────────────────────────────────┘ The --- Above cached, below not cached --- divider is a clever design — Anthropic API supports prompt caching, and caching the above portion can significantly reduce token costs per API call. When the AI's response hits the max tokens limit, the model cuts off output midway. A normal API call ends here — but the Agent cannot stop. BoxAgnts' solution is clever: js // boxagnts-query/src/query.rs const MAX TOKENS RECOVERY LIMIT: u32 = 3; const MAX TOKENS RECOVERY MSG: &str = "Output token limit hit. Resume directly — no apology, no recap of what \ you were doing. Pick up mid-thought if that is where the cut happened. \ Break remaining work into smaller pieces."; When stop reason == "max tokens" is detected: MAX TOKENS RECOVERY MSG The details in the prompt are worth noting — "no apology, no recap" — because an LLM's instinctive reaction after being cut off is "Sorry, I was interrupted, let me start over..." This leads to useless output. This prompt directly forbids that pattern. An LLM's context window is finite. As conversations grow longer and tool results pile up, there comes a moment when things no longer fit. BoxAgnts' response is automatic compaction. The trigger condition is when token estimation reaches 90% of the context window: js // boxagnts-query/src/compact.rs const AUTOCOMPACT TRIGGER FRACTION: f64 = 0.90; const WARNING PCT: f64 = 0.80; // Warning at 80% const CRITICAL PCT: f64 = 0.95; // Critical warning at 95% The core compaction strategy is calling another LLM to "summarize" the conversation history: Original conversation potentially thousands of messages │ ▼ Compaction Prompt NO TOOLS PREAMBLE → force summary mode │ ▼ LLM generates structured summary: · Primary Request and Intent · Key Technical Concepts · Files and Code Sections · Errors and fixes · Pending Tasks · Current Work │ ▼ Summary replaces early conversation history, last 10 messages kept in original form The compaction prompt has a key design — NO TOOLS PREAMBLE : CRITICAL: Respond with TEXT ONLY. Do NOT call any tools. - Do NOT use Read, Bash, Grep, Glob, Edit, Write, or ANY other tool. - You already have all the context you need in the conversation above. - Tool calls will be REJECTED and will waste your only turn. If the compacting LLM tries to call tools, the entire compaction is wasted. This preamble prevents such meta-recursion. When the LLM returns stop reason == "tool use" , the conversation enters the tool execution phase: ┌──────────────────────────────────────────────┐ │ Phase 1: Sequential PreToolUse preprocessing │ │ Each tool block processed sequentially, │ │ can interrupt execution │ ├──────────────────────────────────────────────┤ │ Phase 2: Parallel execution of non-blocking │ │ tools │ │ join all futures → all tools run concurrently │ │ Blocking tools return pre-computed error │ │ results │ └──────────────────────────────────────────────┘ Key design point: tool results are injected in user message format . This leverages LLM message role semantics — the Assistant initiated the tool call, and the User i.e., the system acting on behalf of the user returned the tool result. The model understands this as "the user answered your request" and naturally proceeds to the next round of reasoning. // boxagnts-query/src/lib.rs async fn execute tool name: &str, input: &Value, tools: & Box<dyn Tool , ctx: &ToolContext, - ToolResult { let tool = tools.iter .find |t| t.name == name ; match tool { Some tool = { debug tool = name, "Executing tool" ; tool.execute input.clone , ctx .await } None = { warn tool = name, "Unknown tool requested" ; ToolResult::error format "Unknown tool: {}", name } } } An extremely simple implementation — a linear search. The tools vector typically has only a dozen elements, so the linear search overhead is negligible. Simplicity is more reliable than complexity. When task complexity exceeds a single Agent's capacity, BoxAgnts provides Managed Agent mode: ┌──────────────────┐ │ Manager Agent │ │ Strong model │ │ like Opus │ │ Plans and │ │ assigns only │ └────────┬─────────┘ │ ┌──────────────┼──────────────┐ ▼ ▼ ▼ ┌──────────┐ ┌──────────┐ ┌──────────┐ │ Executor │ │ Executor │ │ Executor │ │ Sonnet │ │ Sonnet │ │ Sonnet │ │ Subtask A│ │ Subtask B│ │ Subtask C│ └──────────┘ └──────────┘ └──────────┘ Parallel execution, each with independent context The Manager's system prompt is injected with managed mode instructions: php pub fn managed agent system prompt config: &ManagedAgentConfig - String { format r " Managed Agent Mode You are the MANAGER in a manager-executor architecture. Your Role - You coordinate work but do NOT execute tasks directly. - Delegate all implementation work to executor agents. - Each executor uses model {executor model} with up to {max turns} turns. - You may run up to {max concurrent} executors in parallel. Workflow 1. Analyze the user's request and break into sub-tasks. 2. Spawn executors using the Agent tool. 3. Review results. If insufficient, spawn follow-up executors. 4. Synthesize all results into a coherent response. " , ... } The Manager does not execute tools itself — it only plans, assigns, and synthesizes results. Executors are ordinary Agent instances with the full tool set. This pattern separates "thinking" from "execution," both avoiding single-Agent context bloat and enabling true parallel processing. Tools are the Agent's "hands" — reading files, writing files, executing commands. Skills are the Agent's "professional knowledge" — code review methodology, CSS refactoring guidelines, frontend component templates. A Skill is simply a SKILL.md file: app/extensions/skills/ ├── code-review/SKILL.md ├── css-refactor-advisor/SKILL.md ├── current-weather/SKILL.md ├── weather-forecast/SKILL.md └── front-component-generator/SKILL.md pub struct SkillTool; async trait impl Tool for SkillTool { fn name &self - &str { "skill-tool" } async fn execute &self, input: Value, ctx: &ToolContext - ToolResult { let params: SkillInput = serde json::from value input ?; // "skill": "list" → List all available skills if params.skill == "list" { return list skills &dirs .await; } // Find and read SKILL.md let skill path, raw = find and read skill &skill name, &dirs .await?; // Strip YAML frontmatter let content = strip frontmatter &raw ; // Replace $ARGUMENTS placeholder let prompt = if let Some args = &params.args { content.replace "$ARGUMENTS", args } else { content.replace "$ARGUMENTS", "" }; ToolResult::success prompt } } Skill search prioritizes the workspace directory, then the app extensions directory: php async fn skill search dirs ctx: &ToolContext - Vec<PathBuf { let mut dirs = vec ctx.get workspace extensions dir .await.join "skills" // Project-level ; dirs.push ctx.get app extensions dir .await.join "skills" ; // Global-level dirs } This means you can define project-specific Skills under your project directory e.g., "Understand this project's build system" while also using global Skills e.g., "Universal code review standards" . Project-level Skills take priority over global Skills. The most critical mechanism in Skill templates is $ARGUMENTS : Code Review Skill Template Please review: $ARGUMENTS Checklist: 1. Are functions too long 50 lines ? 2. Are there unhandled Result/Option cases? 3. Are there unnecessary .clone calls? 4. Does naming follow Rust conventions? When the AI calls with args: "src/main.rs" , $ARGUMENTS is replaced with src/main.rs . This turns Skills from "static knowledge" into "parameterized tools." The entire query loop pushes status in real-time through the event tx channel: pub enum QueryEvent { Token { text: String }, // Per-token push ToolStart { tool name, tool id, input }, // Tool start ToolEnd { tool name, tool id, result }, // Tool end Status String , // Status message } These events are pushed to the Dashboard frontend in real-time via WebSocket, allowing users to see every decision the Agent makes — not facing a black box. An AI Agent's multi-turn conversation is a complex control system: System Prompt → API Call → Stream Parse → Tool Detection → Tool Execution → Result Injection → Call Again ↑ │ └───────────────── Loop until end turn ───────────────────────────────────┘ The robustness of this loop depends on: | Mechanism | Problem Solved | |---|---| | Agent definition system | Multi-role, multi-model switching | | System prompt construction | Agent worldview + prompt caching | | max tokens recovery | Long output truncation | | auto compact structured summaries | Context overflow beyond window | | tool result budget | Tool result accumulation |