如果你只和 ChatGPT 聊过天你可能会觉得 AI Agent 就是“把 prompt 发给 API，把回复显示来”。

实际痛点：

• 在真实项目中，单轮对话根本无法完成复杂的编辑、搜索或部署任务。
• 工具调用往往不透明，开发者难以追踪哪一步触发了哪个工具。
• 有限，长时间交互会导致历史信息被截断或遗失。
• 模型经常因 token 限制被强行中止，导致业务流程中断。
• 不同阶段需要不同模型或权限，却没有统一的切换机制。

下面通过 BoxAgnts 中一个完整的 Agent 交互流程，展示如何解决这些痛点：

使用者输入："帮我读一下 config.toml。把 port 改成 8080"
· 使用者消息加入对话历史
· 建立 system prompt
· 调用 LLM API → 流式接收响应
· AI 决定调用工具：tool_use
· 执行 read 工具
· 工具结果注入对话历史
·
调用 API → AI 分析配置
· AI 决定调用工具：tool_use
· 执行 edit 工具
· 工具结果注入对话
·
调用 API → AI 回复："已将端口从 8000 改为 8080"
· end_turn → 对话结束

这个过程涉及 5 次 API 调用、2 次工具执行、流式推送、上下文管理。

Agent 定义：给 Agent 一个“身份”

在开始推理循环之前，需要先定义 Agent 的“角色”。BoxAgnts 内置了三个预置 Agent：

// boxagnts-workspace/src/config.rs
pub struct AgentDefinition {
pub description: Option,// 描述
pub model: Option,// 模型覆盖
pub temperature: Option,// 温度覆盖
pub prompt: Option,// 程序提示前缀
pub access: String,// 权限：full / read-only / search-only
pub visible: bool,// 是否在 @agent 自动补全中显示
pub max_turns: Option,// 最大轮次覆盖
pub color: Option。// 终端显示颜色
}

预置的三个 Agent 角色：

Agent prompt 如何注入

Agent 定义中的 prompt 字段会在查询循环启动时被注入到 system prompt 的最前面：

// boxagnts-query/src/query.rs
if let Some = config.agent_definition {
if let Some = agent.prompt {
patched.system_prompt = Some(match &config.system_prompt {
Some => format!,None => agent_prompt.clone,});}
}

Agent 可以覆盖模型和最大轮次：

let effective_model = if let Some = config.agent_definition {
agent.model.clone.unwrap_or_else)
} else {
config.model.clone
};let effective_max_turns = config.agent_definition
.as_ref
.and_n
.unwrap_or;

这代表着使用者可以在同一会话中和权限——规划阶段使用只读慢思考模型。执行阶段切换到全权限快速模型，从根本上缓解 “单一模型难兼顾所有需求” 的痛点。

run_query_loop：Agent 的心脏

run_query_loop 是 BoxAgnts 中最主要的函数，位于 boxagnts-query crate 中：

pub async fn run_query_loop(
说到client，&AnthropicClient,// API 客户端
messages: &mut Vec。// 对话历史
tools这方面，&,// 工具集合
tool_ctx: &ToolContext,// 沙箱配置
再看config，&QueryConfig,// 循环配置
cost_tracker: Arc,// 成本追踪，防止预算超支
event_tx: Option,// 实时事件推送
cancel_token: CancellationToken,// 使用者可随时中断循环
pending_messages: Option<&mut Vec,// 插入式使用者消息
) -> QueryOutcome {…}

The signature itself is a design document—each parameter solves a concrete production problem:

主循环的五步节拍

┌─────────────────────────────────────────────┐│ loop { ││ ││ ① 检查终止条件 ││ · turn> max_turns?→ EndTurn ││ · cancel_token?说起来，→ Cancelled ││ · budget exceeded?话说回来，→ BudgetExceeded ││ ││ ② 预处理消息 ││ · drain pending_messages queue ││ · apply_tool_result_budget ││ · auto_compact ││ ││ ③ 建立 system prompt + 调用 LLM API ││ · 注入 Agent 定义 / AGENTS.md ││ · 建立 CreateMessageRequest ││ · 流式接收 StreamEvent ││ · 累积 text / thinking / tool_use blocks││ ││ ④ 处理响应 ││ · end_turn → 返回 ││ · tool_use → 并行执行工具 → 注入结果 → 继续 ││ · max_tokens → 恢复输出 → 继续 ││ ││ ⑤ 错误恢复 ││ · overloaded → 切换 fallback model ││ · stream stall → retry │└─────────────────────────────────────────────┘

System Prompt 建立：Agent 的“世界观”

A well‑structured system prompt gives model a stable “worldview”。从而降低每轮 token 消耗并提高可靠性。

fn build_system_prompt -> SystemPrompt {
let opts = SystemPromptOptions {
custom_system_prompt: config.system_prompt.clone,append_system_prompt: config.append_system_prompt.clone。output_style: config.output_style,custom_output_style_prompt: config.output_style_prompt.clone,working_directory: config.working_directory.clone,..Default::default
};let text = boxagnts_core::system_prompt::build_system_prompt;
SystemPrompt::Text
}

The prompt is layered:

┌──────────────────────────────────────┐
│ Agent 角色定义 ← AgentDefinition.prompt
├──────────────────────────────────────┤
│ 主要能力声明 │
│ • 可用工具列表 ← 动态生成自 tools 参数 |
│ • 技能列表 ← SkillTool 自动发现 |
│ • 输出格式要求 |
│ • 安全边界 |
├──────────────────────────────────────┤
│ AGENTS.md 内容 ← 项目级行为规范 |
├──────────────────────────────────────┤
│ 动态边界标记 |
│ --- 以上缓存。以下不缓存 --- |
├──────────────────────────────────────┤
│ 会话特定信息 ← 工作目录、时间等 |
└──────────────────────────────────────┘

The “---以上缓存---” line leverages Anthropic’s prompt caching,dramatically cutting token cost for repeated calls.

max_tokens 恢复：Agent 的“断点续传”

If model hits its token limit,a naïve implementation would abort task entirely. BoxAgnts instead automatically resumes from cut‑off point.

// boxagnts-query/src/query.rs
const MAX_TOKENS_RECOVERY_LIMIT: u32 = /* configurable */;const MAX_TOKENS_RECOVERY_MSG: &'static str =
"Output token limit hit. Resume directly — no apology,no recap of what \
you were doing. Pick up mid-thought if that is where cut happened. \
Break remaining work into smaller pieces.";

1. Add partial assistant reply to history.
2. Add a syntic user message containing MAXTOKENSRECOVERY_MSG.
3. The next loop call continues generation exactly where it left off.
4. The explicit “no apology。no recap” instruction prevents model from inserting useless filler sentences.
"

auto_compact：当上下文太长时

L​LM context windows are finite. When conversation history grows beyond a configurable fraction of window,BoxAgnts automatically compacts it by summarizing older turns.

// boxagnts-query/src/compact.rs
const AUTOCOMPACT_TRIGGER_FRACTION: f64 = /* e.g.,0.75 */;const WARNING_PCT: f64 = /* e.g.,0.80 */;const CRITICAL_PCT: f64 = /* e.g.,0.90 */;

The summarization uses an auxiliary LLM with a strict “NO_TOOLS_PREAMBLE” to guarantee that no tool calls happen during compression:

CRITICAL:
Respond with TEXT ONLY. Do NOT call any tools.
- Do NOT use Read,Bash,Grep,Glob,Edit,Write,or ANY or tool.
- You already have all context you need in conversation above.
- Tool calls will be REJECTED and will waste your only turn.

The result replaces early messages while preserving most recent few turns verbatim.

Tool 执行：从 AI 决定到运行结果

If LLM returns "tool_use"。BoxAgnts enters tool execution phase:

┌──────────────────────────────────────────────┐
| Phase : 顺序执行 PreToolUse 预处理 |
| |
├──────────────────────────────────────────────┤
| Phase : 并行执行非阻塞工具 |
| join_all → 所有工具并发运行 |
| |
└──────────────────────────────────────────────┘

The crucial design choice is to inject tool results back into conversation as **user** messages:

• The Assistant initiated "tool_use".
• The system replies with "tool_result".
• The model treats this as normal user feedback and proceeds to next reasoning step.
• This pattern keeps whole pipeline within standard chat schema—no special side‑channel needed.
)

execute_tool：工具分发的主要

// boxagnts-query/src/lib.rs

async fn execute_tool( 说到name，&str,input:&Value,tools:&,ctx:&ToolContext,) -> ToolResult { let tool = tools.iter.find == name);match tool { Some=>{ debug!，tool.execute,ctx).await } None=>{ warn!，ToolResult::error) } } }

The implementation is deliberately simple—a linear scan over a small vector is negligible compared to network latency and sandbox startup time.

托管 Agent 模式：Manager‑Executor 架构

If a single Agent cannot handle a complex request alone,BoxAgnts offers a managed‑agent mode that separates planning from execution.

┌───────────────────┐
│   Manager Agent  │
├─ Opus 等强模型   ┤
|   只做规划和分配   |
└─────────▲─────────┘
|
┌─────────────╂─────────────╂─────────────┐
▼             ▼             ▼
┌───────────┐ ┌───────────┐ ┌───────────�╗
| Executor A | | Executor B | | Executor C |
| | | | | |
| 子任务 A   | | 子任务 B   | | 子任务 C   |
└───────────�╝ └──────────�╝ └──────────�╝ 

The Manager’s system prompt contains explicit directives so it never calls tools directly—it only spawns Executors via an internal agent tool.

Managed‑Agent Prompt 示例

pub fn managedagentsystem_prompt->String{
format!(r#"

Managed Agent Mode

You are THE MANAGER in a manager‑executor architecture.

Your Role

• Coordinate work but DO NOT execute tasks yourself.
• Delegate implementation to executor agents.
• Each executor runs model {executor_model} with up to {max_turns} turns.
• You may launch up to {max_concurrent} executors in parallel.

Workflow

1️⃣ Analyze user request & break into sub‑tasks. 2️⃣ Spawn executors via agent tool. 3️⃣ Review results – if insufficient spawn follow‑ups. 4️⃣ Synsize all outcomes into final response."#。...)) }

Skill 程序：让 Agent 学会“专业技能”

A Tool gives an Agent physical capabilities . A Skill provides domain expertise—e.g.,code‑review guidelines or CSS refactoring advice.

Skill 文件结构

app/extensions/skills/
├── code-review/
│   └── SKILL.md # 静态模板 + $ARGUMENTS 占位符
├── css-refactor-advisor/
├── current-wear/
...

Each SKILL.md may contain front‑matter metadata followed by markdown content.

SkillTool 实现

pub struct SkillTool;

impl Tool for SkillTool { fn name->&'static str{ "skill-tool" }

async fn execute->ToolResult{ let params :SkillInput = serdejson::fromvalue?，if params.skill=="list"{ return listskills.await;} let =findandreadskill.await?，其实，let content = strip_frontmatter;let rendered = match ¶ms.args{ Some=>content.replace。None=>content.replace,};ToolResult::success } }

双层搜索方法

async fn skillsearchdirs->Vec{
let mut dirs = vec!，// 项目级优先
dirs.push.await.join );// 全局备用
dirs
}

Thus developers can override global skills with project‑specific versions—a direct answer to “在不同项目里需要不同规则，却不想改代码”的痛点。

$ARGUMENTS 占位符

示例 SKILL.md 内容：

`markdown

至于请审查，$ARGUMENTS

至于检查要点，* 函数是否过长 * 是否存在未处理的 Result/Option * 是否有不必要的 .clone * 命名是否符合 Rust 惯例 `

When invoked as:

json { "skill":"code-review","args":"src/main.rs" }

$ARGUMENTS placeholder becomes src/main.rs。turning static knowledge into a dynamic advisory function.

流式推送的观点是，让使用者看到 Agent 在“思考”

The query loop emits granular events through an unbounded channel which can be streamed to UI dashboards or TUI clients:

pub enum QueryEvent{
Token{ text:String },// 每个 token 实时推送
ToolStart{toolname:String,toolid:u64,input:String},ToolEnd{toolname:String,toolid:u64,result:String},Status,// 状态文字，例如 “正在压缩上下文…”
}

These events enable transparent debugging—developers no longer face “AI 突然卡死，我不知道它在干什么”的困惑。

小结

An AI Agent’s multi‑turn dialogue is essentially a robust control loop:

System Prompt ➜ API Call ➜ Stream Parse ➜ Detect Tool Use ➜ Execute Tool ➜ Inject Result ➜ Loop again ⟲ until end_turn

Each mechanism in BoxAgnts directly addresses real production pains:

Model overload / rate limits fallback_model switching Complex tasks exceeding single-agent capacity Managed‑Agent mode – Manager + Executors Lack of domain expertise Skill system – parametric knowledge injection Slow feedback loop for users Event streaming via QueryEvent

Pain Point	Solved By	Diverse roles & models needed per stage	Agent Definition System – role + model overrides	Prompt length growth causing cost explosion	Layered System Prompt + Caching	Output truncation at token limit	max_tokens Recovery logic	Context window overflow	auto_compact structural summary	Tool result accumulation bloat tool_result_budget trimming

Implementing se mechanisms transforms an “AI 能跑” prototype into a production‑ready “AI 能可靠工作” platform.