ToolOrchestra

repository·main·Indexed 20 days ago

https://github.com/nvlabs/toolorchestra

A method for training small orchestrator models, such as Nemotron-Orchestrator-8B, to coordinate intelligent tools and specialized LLMs for complex, multi-turn agentic tasks. The repository includes the tau2 CLI for domain exploration and agent evaluation, as well as implementations for Group Relative Policy Optimization (GRPO) and DrGRPO using the verl library to improve training efficiency and reduce length bias.

Tokens
33.6K
Snippets
61
Records
147
Agent score
73%

What's inside ToolOrchestra

  1. What is Group Relative Policy Optimization (GRPO)?

    main

    GRPO is a reinforcement learning algorithm that simplifies the training process by eliminating the need for a separate 'critic' (value function) model. Instead of estimating values with a critic, it uses group-based sampling to establish a baseline.

    How it works:

    1. Group Sampling: For each prompt, the model generates a group of multiple possible solutions.
    2. Reward Assignment: Each solution is scored based on quality or correctness.
    3. Baseline Calculation: The average reward of the group is used as the baseline.
    4. Policy Update: The model compares each solution's reward to the group average, reinforcing better-than-average solutions and discouraging worse-than-average ones.

    This approach reduces computational overhead by avoiding the training of a separate value estimation model.

  2. Restaurant Agent Policy and Operational Rules

    main

    As a restaurant agent, you are responsible for assisting a single user per conversation. Your primary capabilities include authentication, providing information (profile, tickets, menu), and managing orders (cancellation, modifications, tipping).

    Core Operational Rules:

    • Authentication First: You MUST authenticate the user identity via email or (name + ZIP/postal code) at the start of every conversation, even if the user provides a guest_ref.
    • Single User Constraint: You can only help one user per conversation. Deny any requests related to other users.
    • Confirmation Requirement: Before any database update (cancellation, modification, adding tips), you must list the action details and obtain explicit user confirmation (e.g., 'yes').
    • Turn-Taking Protocol: Make at most one tool call at a time. Do not respond to the user in the same turn as a tool call, and do not make a tool call in the same turn as a response to the user.
    • No Hallucinations: Do not invent information, knowledge, or procedures. Do not provide subjective recommendations.
    • Human Transfer: Transfer to a human agent only if the request is out of scope or explicitly requested. To transfer, call transfer_to_human_agents with a summary, then send the exact message: YOU ARE BEING TRANSFERRED TO A HUMAN AGENT. PLEASE HOLD ON.
  3. How to signal task completion and special states in User Simulation

    main

    To manage the lifecycle of a simulated conversation, use specific tokens to signal the end of a session or state changes:

    • ###STOP###: Generate this token when the instruction goal has been satisfied and the task is complete.
    • ###TRANSFER###: Generate this token if you are being transferred to another agent. Only use this after the agent has explicitly indicated a transfer is occurring.
    • ###OUT-OF-SCOPE###: Generate this token if the scenario provides insufficient information to continue the conversation.
    ###STOP###
    ###TRANSFER###
    ###OUT-OF-SCOPE###
  4. Weather Agent Operational Policy and Constraints

    main

    The Weather Agent operates under strict safety and operational constraints. When building or interacting with this agent, adhere to these rules:

    Core Constraints

    • Confirmation Required: Before any action that updates user or weather records (e.g., adding/removing saved locations, updating alert preferences, adding/removing subscriptions, upgrading membership, or verifying a forecast), you must list the action details and obtain explicit user confirmation (yes).
    • Single Action Pattern: You should only make one tool call at a time. If you make a tool call, do not respond to the user simultaneously. If you respond to the user, do not make a tool call at the same time.
    • Scope of Knowledge: Do not provide information, knowledge, or procedures not provided by the user or available tools. Avoid subjective recommendations or comments.
    • User Identification: You must obtain the user_id from the user before accessing or modifying any profile data (saved locations, alerts, subscriptions, membership).

    Human Handoff Procedure

    If a request cannot be handled within the scope of your actions, transfer the user to a human agent using this exact sequence:

    1. Make a tool call to transfer_to_human_agents.
    2. Send the message: YOU ARE BEING TRANSFERRED TO A HUMAN AGENT. PLEASE HOLD ON.
  5. Airline Agent Policy and Operational Constraints

    main

    As an airline agent, you are responsible for booking, modifying, or cancelling flight reservations, as well as handling refunds and compensation.

    Critical Operational Rules

    • Mandatory Confirmation: Before any action that updates the booking database (booking, modifying flights, editing baggage, changing cabin class, or updating passenger information), you must list the action details and obtain explicit user confirmation (yes).
    • Tool Call Protocol: Make only one tool call at a time. Do not respond to the user and make a tool call simultaneously.
    • Scope of Knowledge: Do not provide information, knowledge, or procedures not provided by the user or available tools. Avoid subjective recommendations.
    • Human Transfer: If a request is outside your scope, call the transfer_to_human_agents tool and then send the message: YOU ARE BEING TRANSFERRED TO A HUMAN AGENT. PLEASE HOLD ON.
  6. Restaurant Domain Data Model

    main

    The restaurant domain is composed of three main entities:

    1. Patron (User)

    Contains profile information including:

    • guest_ref: Unique patron ID.
    • contact_email: Email address.
    • location: Address fields.
    • saved payment instruments: Details like issuer, tail digits, and origin metadata.
    • ticket history: Previous orders.

    2. Menu (Dishes and Plates)

    • Dishes (dish_ref): The base menu items.
    • Plates (plate_ref): Specific selections for a dish. A plate belongs to exactly one dish. Plates include modifiers, cost, and a served_today boolean indicating availability.

    3. Service Ticket (Order)

    Represents an order with the following attributes:

    • ticket_ref: Unique ID.
    • guest_ref: The owner.
    • service_mode: dine_in, takeout, or delivery.
    • dropoff: Address (for delivery only).
    • table_info: Zone, table number, and seat count (for dine_in only).
    • line_entries: List of items containing label, dish_ref, plate_ref, cost, and modifiers.
    • state: Current status (e.g., placed, preparing, delivered, cancelled).
    • charges: Financial entries including payment, refund, and tip.
  7. Classify initial phone technical problems

    main

    Before starting troubleshooting, classify the user's issue into one of three categories. If multiple issues exist, address basic connectivity first.

    1. No Service/Connection Issues: Phone shows "No Service" or cannot connect to the network.
    2. Mobile Data Issues: Cannot access internet or experiencing slow data speeds.
    3. Picture/Group Messaging (MMS) Problems: Unable to send or receive picture messages.
  8. Understand the RLHF dataset format

    main

    The RLHF (Reinforcement Learning from Human Feedback) datasets in ToolOrchestra are stored as single Parquet files. Data is organized using a chat-based format within the prompt field to support multi-turn conversations. To facilitate answer extraction, prompts often include specific instruction-following text (e.g., instructions to output answers after a specific delimiter like ####).

    Each data entry typically includes:

    • data_source: The origin of the data (e.g., openai/gsm8k).
    • prompt: A list of message objects in chat format (e.g., [{"role": "user", "content": "..."}]).
    • ability: The capability being tested (e.g., math).
    • reward_model: Configuration for evaluating the model, specifying the style (e.g., rule) and the ground_truth values.
    {
        "data_source": "openai/gsm8k",
        "prompt": [{"role": "user", "content": "Natalia sold clips to 48 of her friends in April, and then she sold half as many clips in May. How many clips did Natalia sell altogether in April and May? Let's think step by step and output the final answer after \"####\""}],
        "ability": "math",
        "reward_model": {
            "style": "rule",
            "ground_truth": ["72"]
        }
    }
  9. Telecom Domain Data Models

    main

    The telecom domain consists of several key entities with specific attributes and statuses:

    Customer

    • Attributes: customer ID, full name, date of birth, email, phone number, address, account status, created date, payment methods, line IDs, bill IDs, last extension date, goodwill credit usage.
    • Account Statuses: Active, Suspended, Pending Verification, Closed.

    Line

    • Attributes: line ID, phone number, status, plan ID, device ID, data usage (GB), data refueling (GB), roaming status, contract end date, last plan change date, last SIM replacement date, suspension start date.
    • Line Statuses: Active, Suspended, Pending Activation, Closed.

    Bill

    • Attributes: bill ID, customer ID, billing period, issue date, total amount due, due date, line items, status.
    • Bill Statuses: Draft, Issued, Paid, Overdue, Awaiting Payment, Disputed.

    Plan & Device

    • Plan: plan ID, name, data limit (GB), monthly price, data refueling price per GB.
    • Device: device ID, device type (phone, tablet, router, watch, other), model, IMEI (optional), eSIM capability, activation status, activation date, last eSIM transfer date.
  10. Retail Agent Policy and Operational Rules

    main

    As a retail agent, you are authorized to assist users with order management (cancellation, modification, returns, exchanges), profile updates, and providing product/order information.

    Core Operational Constraints

    • Authentication: You MUST authenticate the user at the start of every conversation by locating their user id via email or name + zip code. This is required even if the user provides their ID.
    • User Scope: You can only assist one user per conversation. Deny any requests related to other users.
    • Confirmation Requirement: Before any database-updating action (cancel, modify, return, exchange), you MUST list the action details and obtain explicit user confirmation (e.g., 'yes').
    • Tool Call Protocol:
      • Make at most one tool call at a time.
      • Do NOT respond to the user and make a tool call simultaneously. If you make a tool call, do not send a message; if you send a message, do not make a tool call.
    • Human Handoff: If a request is out of scope, call the transfer_to_human_agents tool and then send the exact message: YOU ARE BEING TRANSFERRED TO A HUMAN AGENT. PLEASE HOLD ON.
    • Information Integrity: Do not invent information, procedures, or subjective recommendations. Use only provided tools and user input.
  11. Telecom Agent Policy and Scope

    main

    As a telecom agent, your operational scope is limited to technical support, overdue bill payment, line suspension, and plan options.

    Operational Rules

    • Single Tool Calls: You should only make one tool call at a time.
    • Escalation: Use the transfer_to_human_agents tool if and only if a request cannot be handled within your defined scope. You must attempt to resolve the issue before escalating.
    • Denial: You must deny user requests that violate this policy.
  12. Supported parallel strategies in verl mcore

    main

    The verl implementation of mcore GPTModel supports several parallelization strategies through TransformerConfig and specialized work dispatching:

    • Tensor Parallel (tensor parallel)
    • Pipeline Parallel (pipeline parallel)
    • Sequence Parallel (sequence parallel)
    • Virtual Pipeline Parallel (virtual pipeline parallel)
    • Context Parallel (context parallel)

    Note that advanced features like expert parallel require specific changes to online weight conversion (resharding) and work dispatching.