updated docs to reflect agent routing and hand off (#443)

* updated docs to reflect agent routing and hand off

* updated prompt targets based on review

---------

Co-authored-by: Salman Paracha <salmanparacha@MacBook-Pro-261.local>

docs/source/concepts/prompt_target.rst

@@ -3,14 +3,13 @@
 Prompt Target
 ==============
 
-**Prompt Targets** are a fundamental component of Arch, enabling developers to define how different types of user prompts are processed and routed within their generative AI applications.
-This section provides an in-depth look at prompt targets, including their purpose, configuration, usage, and best practices to help you effectively leverage this feature in your projects.
+**Prompt Targets** are a core concept in Arch, empowering developers to clearly define how user prompts are interpreted, processed, and routed within their generative AI applications. Prompts can seamlessly be routed either to specialized AI agents capable of handling sophisticated, context-driven tasks or to targeted tools provided by your application, offering users a fast, precise, and personalized experience.
+
+This section covers the essentials of prompt targets—what they are, how to configure them, their practical uses, and recommended best practices—to help you fully utilize this feature in your applications.
 
 What Are Prompt Targets?
 ------------------------
-Prompt targets are predefined endpoints within Arch that handle specific types of user prompts.
-They act as the bridge between user inputs and your backend services or APIs, enabling Arch to route, process, and manage prompts efficiently.
-By defining prompt targets, you can separate your application's business logic from the complexities of prompt processing, ensuring a cleaner and more maintainable codebase.
+Prompt targets are endpoints within Arch that handle specific types of user prompts. They act as the bridge between user inputs and your backend agemts or tools (APIs), enabling Arch to route, process, and manage prompts efficiently. Defining prompt targets helps you decouple your application's core logic from processing and handling complexities, leading to clearer code organization, better scalability, and easier maintenance.
 
 
 .. table::
@@ -21,7 +20,7 @@ By defining prompt targets, you can separate your application's business logic f
     ====================    ============================================
     Intent Recognition      Identify the purpose of a user prompt.
     Parameter Extraction    Extract necessary data from the prompt.
-    API Invocation          Call relevant backend services or functions.
+    Invocation              Call relevant backend agents or tools (APIs).
     Response Handling       Process and return responses to the user.
     ====================    ============================================
 
@@ -30,16 +29,15 @@ Key Features
 
 Below are the key features of prompt targets that empower developers to build efficient, scalable, and personalized GenAI solutions:
 
-- **Modular Design**: Define multiple prompt targets to handle diverse functionalities.
-- **Parameter Management**: Specify required and optional parameters for each target.
-- **Function Integration**: Seamlessly connect prompts to backend APIs or functions.
+- **Design Scenarios**: Define prompt targets to effectively handle specific agentic scenarios.
+- **Input Management**: Specify required and optional parameters for each target.
+- **Tools Integration**: Seamlessly connect prompts to backend APIs or functions.
 - **Error Handling**: Direct errors to designated handlers for streamlined troubleshooting.
 - **Metadata Enrichment**: Attach additional context to prompts for enhanced processing.
 
 Configuring Prompt Targets
 --------------------------
-Configuring prompt targets involves defining them in Arch's configuration file.
-Each Prompt target specifies how a particular type of prompt should be handled, including the endpoint to invoke and any parameters required.
+Configuring prompt targets involves defining them in Arch's configuration file. Each Prompt target specifies how a particular type of prompt should be handled, including the endpoint to invoke and any parameters required.
 
 Basic Configuration
 ~~~~~~~~~~~~~~~~~~~
@@ -50,7 +48,7 @@ A prompt target configuration includes the following elements:
 
 - ``name``: A unique identifier for the prompt target.
 - ``description``: A brief explanation of what the prompt target does.
-- ``endpoint``: The API endpoint or function that handles the prompt.
+- ``endpoint``: Required if you want to call a tool or specific API. ``name`` and ``path`` ``http_method`` are the three attributes of the endpoint.
 - ``parameters`` (Optional): A list of parameters to extract from the prompt.
 
 .. _defining_prompt_target_parameters:
@@ -69,6 +67,7 @@ Each parameter can be marked as required or optional. Here is a full list of par
     ``name (req.)``           Specifies name of the parameter.
     ``description (req.)``    Provides a human-readable explanation of the parameter's purpose.
     ``type (req.)``           Specifies the data type. Supported types include: **int**, **str**, **float**, **bool**, **list**, **set**, **dict**, **tuple**
+    ``in_path``               Indicates whether the parameter is part of the path in the endpoint url. Valid values: **true** or **false**
     ``default``               Specifies a default value for the parameter if not provided by the user.
     ``format``                Specifies a format for the parameter value. For example: `2019-12-31` for a date value.
     ``enum``                  Lists of allowable values for the parameter with data type matching the ``type`` attribute. **Usage Example**: ``enum: ["celsius`", "fahrenheit"]``
@@ -76,10 +75,11 @@ Each parameter can be marked as required or optional. Here is a full list of par
     ``required``              Indicates whether the parameter is mandatory or optional. Valid values: **true** or **false**
     ========================  ============================================================================
 
-Example Configuration
-~~~~~~~~~~~~~~~~~~~~~
+Example Configuration For Tools
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 .. code-block:: yaml
+    :caption: Tools and Function Calling Configuration Example
 
     prompt_targets:
       - name: get_weather
@@ -98,16 +98,35 @@ Example Configuration
           name: api_server
           path: /weather
 
+Example Configuration For Agents
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+.. code-block:: yaml
+    :caption: Agent Orchestration Configuration Example
+
+    overrides:
+      use_agent_orchestrator: true
+
+    prompt_targets:
+      - name: sales_agent
+        description: handles queries related to sales and purchases
+
+      - name: issues_and_repairs
+        description: handles issues, repairs, or refunds
+
+      - name: escalate_to_human
+        description: escalates to human agent
+
+.. note::
+    Today, you can use Arch to coordinate more specific agentic scenarios via tools and function calling, or use it for high-level agent routing and hand off scenarios. In the future, we plan to offer you the ability to combine these two approaches for more complex scenarios. Please see `github issues <https://github.com/katanemo/archgw/issues/442>`_ for more details.
 
 Routing Logic
 -------------
-Prompt targets determine where and how user prompts are processed.
-Arch uses intelligent routing logic to ensure that prompts are directed to the appropriate targets based on their intent and context.
+Prompt targets determine where and how user prompts are processed. Arch uses intelligent routing logic to ensure that prompts are directed to the appropriate targets based on their intent and context.
 
 Default Targets
 ~~~~~~~~~~~~~~~
-For general-purpose prompts that do not match any specific prompt target, Arch routes them to a designated default target.
-This is useful for handling open-ended queries like document summarization or information extraction.
+For general-purpose prompts that do not match any specific prompt target, Arch routes them to a designated default target. This is useful for handling open-ended queries like document summarization or information extraction.
 
 Intent Matching
 ~~~~~~~~~~~~~~~
@@ -124,5 +143,5 @@ For example:
 Summary
 --------
 Prompt targets are essential for defining how user prompts are handled within your generative AI applications using Arch.
-By carefully configuring prompt targets, you can ensure that prompts are accurately routed, necessary parameters are extracted, and backend services are invoked seamlessly.
-This modular approach not only simplifies your application's architecture but also enhances scalability, maintainability, and overall user experience.
+
+By carefully configuring prompt targets, you can ensure that prompts are accurately routed, necessary parameters are extracted, and backend services are invoked seamlessly. This modular approach not only simplifies your application's architecture but also enhances scalability, maintainability, and overall user experience.