# BoxAgnts Introduction (6) — Agent Multi-Turn Conversation and Tool/Skill Invocation > Source: > Published: 2026-05-30 13:26:18+00:00 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, // Description" pub model: Option, // Model override pub temperature: Option, // Temperature override pub prompt: Option, // System prompt prefix pub access: String, // Permission: full / read-only / search-only pub visible: bool, // Whether visible in @agent autocomplete pub max_turns: Option, // Max turns override pub color: Option, // 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, // Conversation history (mutable reference) tools: &[Box], // Tool collection tool_ctx: &ToolContext, // Tool execution context config: &QueryConfig, // Loop configuration cost_tracker: Arc, // Cost tracking event_tx: Option>, // Event push cancel_token: CancellationToken, // Cancellation signal pending_messages: Option<&mut Vec>, // 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` | Directly modifies conversation history, appends content each iteration | `tools: &[Box]` | 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], 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) = ¶ms.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 { 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 |