AgentTune: A Unified Training Lifecycle for Tool-Using LLM Agents
Organizations: Lexsi Labs
Abstract
Tool-using agents increasingly require a common substrate for building, training, evaluating, distilling, and maintaining agentic systems, yet existing tooling typically addresses these stages in isolation. We present AgentTune, a source-available Python library that provides a unified framework for developing and optimizing tool-using agents. At its core, AgentTune introduces a two-tier EventLog representation that preserves agent trajectories while supporting consistent projections for training, evaluation, and auditing. Building on this substrate, the library provides a shared agent runtime, tool-calling reinforcement learning, agentic distillation, retrieval-augmented generation, decision workflows, evaluation utilities, and a designed path toward self-healing agents. These components are exposed through composable interfaces so that agent strategies, training methods, evaluation procedures, and recovery mechanisms can be combined without requiring separate representations or pipelines. We demonstrate the framework across agentic tasks including legal contract search and domain-specific applications, illustrating its use for trajectory-based optimization, tool-use evaluation, and cross-task agent development. AgentTune is released as a source-available library at https://github.com/Lexsi-Labs/AgentTune
Figures & tables
| Layer | Package | Contents | Described in |
|---|---|---|---|
| 1 Interfaces | cli/ | the agenttune console commands and the decide sub-app; the Python SDK and the [service] FastAPI app are the other three entry points | § 3.12 |
| 2 Agent runtime | agentic/ | five strategies, three memory backends and TrajectoryStore , two harnesses, and the Project lifecycle | § 3.4 |
| 3 Unified trajectory | agentic/ events.py | the EventLog schema, its two tiers, and the six projections in and out | § 3.3 |
| 4 Learning and evaluation | core/ , backends/ , rag/ , langgraph/ , eval/ | create_agentic_trainer and the five TrlAgentic* wrappers; three SearchBackend implementations and the six-stage synthesis pipeline; AgentTuneGraph ; BaseEvaluator / RLEvaluator , TrajectoryEvaluator , the lm-eval runner and run_eval ; rollout engines and the 26-entry reward registry | § 3.5 –§ 3.7 , § 3.10 , § 3.11 |
| 5 Production and improvement | decide/ | GraphRunner , the eight stage types, 24 templates, the append-only audit log, and closed_loop/ | § 3.8 , § 3.9 |
| — | data/ , utils/ , scenarios/ | DataManager , device and environment diagnostics, checkpoint helpers, scripted domain scenarios | out of scope (§ 3.1 ) |
| Projection | Direction | Tier produced / required |
|---|---|---|
| from_trajectory | RL rollout EventLog | full |
| from_pipeline_state | DECIDE state EventLog | light |
| from_eval_dict | eval dict EventLog | light |
| as_dataset_rows("sft") | EventLog SFT rows | requires full |
| to_eval_dict | EventLog eval dict | either |
| to_audit_records | EventLog audit log | either |
| Event kind | Chat role | Segment weight |
|---|---|---|
| REASONING / TEXT | assistant | |
| TOOL_CALL | assistant | |
| TOOL_RESULT | tool | |
| OBSERVATION | user |
| Algorithm | Needs | Rollout modes |
|---|---|---|
| GRPO [ 15 ] | reward function(s) | agentic tool loop; combine_rewards applied |
| DPO [ 16 ] | chosen / rejected , or a reward fn | offline; reward-ranked; agentic |
| PPO [ 17 ] | reward fn/model and value fn/model | agentic; patches batch_generation |
| RLOO [ 18 ] | reward function | agentic; reward fn forwarded as-is |
| BCO [ 19 ] | completion / label , or a reward fn | offline; online (regenerates per epoch) |
| Stage type | What it does |
|---|---|
| llm_call | one model call, reply validated against an output_schema |
| router | LLM-based (has a model: ) or rules-based (no model: ) dispatch to one of several on_result targets, through one stage type |
| llm_judge | scores an upstream output on a rubric |
| rules | deterministic gate: a list of condition strings over stage_outputs , evaluated by a hand-written AST walker (only == != < <= > >= and or not , dotted lookups, JSON literals; no eval() , no function calls); first failing rule short-circuits with goto + inject |
| parallel | fan-out to independent branches, run concurrently via asyncio.gather , merged back into stage_outputs by branch id |
| tool_call | invoke a tool from the same registry the spine uses, with interpolated args and a per-stage timeout |
| # | Name | Fires when |
|---|---|---|
| T1 | total_failures_exceeded | buffer size threshold |
| T2 | dominance:<type> | one root_cause the dominance ratio of the buffer |
| T3 | enough_examples | accepted-example count minimum |
| T4 | reward_drift | rolling mean episode reward drifts below baseline |
| T5 | novel_failure:<type> | a never-seen root_cause recurs a minimum count |
| T6 | staleness | time since last retrain a window, with a minimum buffer |
| Metric | Measures |
|---|---|
| TAC | tool-argument correctness, jsonschema-validated against registered schemas |
| ARR | API-redundancy ratio: duplicate calls / total |
| SCSR | self-correction success rate: recovered from a trailing error |
| RAD | reasoning-to-action density (character-count proxy) |
| LCF | loop-collapse frequency: 3+ identical consecutive calls |
| PAS | plan adherence: planned steps that appear in the trajectory |
| Path | Setup | Result |
|---|---|---|
| Distillation (SFT) | SmolLM2-360M [ 41 ] , 16 teacher trajectories, LoRA, 7 s | train loss ; token acc. ; contract learned |
| GRPO (on-policy) | SmolLM2-360M, 90 steps, contract-only reward | mean reward ; contract rate ; correct-label |
| Self-heal DPO | 12 corrective preference pairs from the heal loop | reward acc. ; final reward margin |
| Model | Exact match (%) | Searches / question |
|---|---|---|
| Base model | 60.0 | 3.00 |
| + GRPO (LoRA) | 69.0 | 2.90 |
| Doc@8 | Searches / question | |||
|---|---|---|---|---|
| Corpus | Base | + GRPO | Base | + GRPO |
| ContractNLI [ 48 ] | 0.58 | 0.69 | 4.2 | 3.8 |
| MAUD [ 46 ] | 0.98 | 1.00 | 5.0 | 4.5 |
| PrivacyQA [ 47 ] | 0.83 | 0.98 | 4.0 | 3.5 |
| Model | Training variant | Precision | Recall | Pass@1 |
|---|---|---|---|---|
| CUAD | ||||
| 0.5B | Base | 36.8 | 34.1 | 29.4 |
| 0.5B | Answer SFT | 38.2 | 24.1 | 28.5 |
| 0.5B | QA + reasoning | 45.1 | 42.0 | 36.5 |
| 0.5B | Trajectory, no mask | 39.4 | 58.2 | 41.0 |
| 0.5B | Masked trajectory | 48.5 | 52.6 | 45.8 |
| Capability | AgentTune | TRL | verl | SkyRL / OpenRLHF | LangChain / CrewAI |
|---|---|---|---|---|---|
| Trains a model at all | ✓ | ✓ | ✓ | ✓ | – |
| GRPO/PPO/DPO/RLOO/BCO via one entry point | ✓ | – | partial | partial | – |
| Agentic tool-calling rollouts native to every algorithm | ✓ | – | ✓ | ✓ | executes tools, no training |
| One trajectory schema across eval / train / distill / heal | ✓ | – | – | – | – |
| Agentic distillation (behavior, not weights alone) | ✓ | – | – | – | – |
| Synthetic multi-hop data with verification | ✓ | – | – | – | – |
Appendix figures & tables4 assets
Supplementary material from the paper’s appendix.
Appendix
| EventKind | Meaning |
|---|---|
| TEXT | model-emitted final text |
| REASONING | model-emitted reasoning / thought |
| TOOL_CALL | a tool / action invocation |
| TOOL_RESULT | the tool’s returned output |
| OBSERVATION | environment / state fed to the agent |
| TURN_COMPLETE | end of one agent turn |
| Registry key | Behavior |
|---|---|
| correctness_reward | parses yes / no ; matches answer , wrong, no match |
| structure_reward | call response content shape: / well-formed, call with no response |
| query_reward | SQL heuristic: penalizes queries, LIMIT 1 , missing WHERE |
| reward_correct_answer | numeric match: exact ( ), within |
| reward_tool_used | if any message has role: tool |
| reward_concise_answer | if the final answer is words |
| Key | Contents |
|---|---|
| trajectories | list[Trajectory] , full step-by-step record incl. tool calls |
| responses | list[str] , final assistant text per rollout |
| rewards | list[float] , all zero unless reward_fn= was passed |
| prompt_ids / completion_ids | token ids (the GRPO contract) |
| logprobs | per-token logprobs |
| tool_call_counts | list[int] , tool calls per rollout |
| Parameter | Value |
|---|---|
| Data | |
| Source corpus | 90 CUAD training contracts [ 31 ] |
| Generated candidates | 5,361 |
| After verification | 4,364 |
| After answerability gate | 3,992 (2–5 hops) |
| Train/validation split | gold-chunk disjoint |
Tool-Using Agents
Tool-using agents plan and act through external tools, APIs, software interfaces, and environments to complete tasks beyond language generation.
See all 289 papers