diff --git a/documentation/CustomizeSolution.md b/documentation/CustomizeSolution.md index c319c219..a867892c 100644 --- a/documentation/CustomizeSolution.md +++ b/documentation/CustomizeSolution.md @@ -15,36 +15,45 @@ This application is an AI-driven orchestration system that manages a group of AI This code has not been tested as an end-to-end, reliable production application- it is a foundation to help accelerate building out multi-agent systems. You are encouraged to add your own data and functions to the agents, and then you must apply your own performance and safety evaluation testing frameworks to this system before deploying it. Below, we'll dive into the details of each component, focusing on the endpoints, data types, and the flow of information through the system. - # Table of Contents -- [Accelerating your own Multi-Agent -Custom Automation Engine MVP](#accelerating-your-own-multi-agent--custom-automation-engine-mvp) +- [Accelerating your own Multi-Agent - Custom Automation Engine MVP](#accelerating-your-own-multi-agent---custom-automation-engine-mvp) - [Technical Overview](#technical-overview) - [Table of Contents](#table-of-contents) - [Endpoints](#endpoints) - [/input\_task](#input_task) - [/human\_feedback](#human_feedback) - - [/get\_latest\_plan\_by\_session/{session\_id}](#get_latest_plan_by_sessionsession_id) - - [/get\_steps\_by\_plan/{plan\_id}](#get_steps_by_planplan_id) + - [/get\_latest\_plan\_by\_session/{session\_id}](#get_latest_plan_by_session-session_id) + - [/steps/{plan\_id}](#stepsplan_id) + - [/agent\_messages/{session\_id}](#agent_messagessession_id) + - [/messages](#messages) - [/delete\_all\_messages](#delete_all_messages) + - [/api/agent-tools](#apiagent-tools) - [Data Types and Models](#data-types-and-models) - [Messages](#messages) - - [InputTask](#inputtask) + - [BaseDataModel](#basedatamodel) + - [AgentMessage](#agentmessage) + - [Session](#session) - [Plan](#plan) - [Step](#step) - - [HumanFeedback](#humanfeedback) + - [PlanWithSteps](#planwithsteps) + - [InputTask](#inputtask) - [ApprovalRequest](#approvalrequest) + - [HumanFeedback](#humanfeedback) + - [HumanClarification](#humanclarification) - [ActionRequest](#actionrequest) - [ActionResponse](#actionresponse) - - [Agents](#agents) - - [Agent Types:](#agent-types) + - [PlanStateUpdate](#planstateupdate) + - [GroupChatMessage](#groupchatmessage) + - [RequestToSpeak](#requesttospeak) + - [Enums](#enums) + - [DataType](#datatype) + - [BAgentType](#bagenttype) + - [StepStatus](#stepstatus) + - [PlanStatus](#planstatus) + - [HumanFeedbackStatus](#humanfeedbackstatus) - [Application Flow](#application-flow) - [Initialization](#initialization) - - [Input Task Handling](#input-task-handling) - - [Planning](#planning) - - [Step Execution and Approval](#step-execution-and-approval) - - [Human Feedback](#human-feedback) - - [Action Execution by Specialized Agents](#action-execution-by-specialized-agents) - [Agents Overview](#agents-overview) - [GroupChatManager](#groupchatmanager) - [PlannerAgent](#planneragent) @@ -52,198 +61,483 @@ Below, we'll dive into the details of each component, focusing on the endpoints, - [Specialized Agents](#specialized-agents) - [Persistent Storage with Cosmos DB](#persistent-storage-with-cosmos-db) - [Utilities](#utilities) - - [`initialize` Function](#initialize-function) + - [`initialize_runtime_and_context` Function](#initialize_runtime_and_context-function) - [Summary](#summary) + ## Endpoints ### /input_task **Method:** POST **Description:** Receives the initial input task from the user. -**Request Body:** `InputTask` +**Request Headers:** + +- `user_principal_id`: User ID (`user_id`) extracted from the authentication header. + +**Request Body:** `InputTask` - `session_id`: Optional string. If not provided, a new UUID will be generated. - `description`: The description of the task the user wants to accomplish. -**Response:** +**Response:** - `status`: Confirmation message. - `session_id`: The session ID associated with the task. - `plan_id`: The ID of the plan generated. +- `description`: The task description. + **Flow:** +1. Validates header and extracts `user_principal_id` as `user_id`. +2. Generates a `session_id` if not provided. +3. Initializes agents and context for the session. +4. Sends the `InputTask` message to the `GroupChatManager`. +5. Returns the `status`, `session_id`, `plan_id`, `description`, and `user_id`. -1. Generates a `session_id` if not provided. -2. Initializes agents and context for the session. -3. Sends the `InputTask` message to the `GroupChatManager`. -4. Returns the `session_id` and `plan_id`. ### /human_feedback **Method:** POST **Description:** Receives human feedback on a step (e.g., approval, rejection, or modification). -**Request Body:** `HumanFeedback` -- `step_id`: ID of the step the feedback is related to. -- `plan_id`: ID of the plan. +**Request Headers:** +- `user_principal_id`: User ID (`user_id`) extracted from the authentication header. + +**Request Body:** `HumanFeedback` +- `step_id`: The ID of the step to provide feedback for. +- `plan_id`: The ID of the plan. - `session_id`: The session ID. - `approved`: Boolean indicating if the step is approved. - `human_feedback`: Optional string containing any comments. - `updated_action`: Optional string if the action was modified. **Response:** - - `status`: Confirmation message. - `session_id`: The session ID. +- `step_id`: The step ID associated with the feedback. + +**Flow:** +1. Validates header and extracts `user_principal_id` as `user_id`. +2. Initializes runtime and context for the session. +3. Sends the `HumanFeedback` message to the `HumanAgent`. +4. Returns the `status`, `session_id`, and `step_id`. + + +### /human_clarification_on_plan + +**Method:** POST +**Description:** Receives human clarification on a plan. + +**Request Headers:** +- `user_principal_id`: User ID (`user_id`) extracted from the authentication header. + +**Request Body:** `HumanClarification` +- `plan_id`: The ID of the plan requiring clarification. +- `session_id`: The session ID associated with the plan. +- `human_clarification`: Clarification details provided by the user. + +**Response:** +- `status`: Confirmation message. +- `session_id`: The session ID associated with the plan. + +**Flow:** +1. Validates header and extracts `user_principal_id` as `user_id`. +2. Initializes runtime and context for the session. +3. Sends the `HumanClarification` message to the `PlannerAgent`. +4. Returns the `status` and `session_id`. + +### /approve_step_or_steps + +**Method:** POST +**Description:** Approves a step or multiple steps in a plan. + +**Request Headers:** + +- `user_principal_id`: User ID (`user_id`) extracted from the authentication header. + +**Request Body:** `HumanFeedback` +- `step_id`: Optional step ID to approve. If not provided, all steps are approved. +- `plan_id`: The ID of the plan. +- `session_id`: The session ID associated with the plan. +- `approved`: Boolean indicating whether the step(s) are approved. +- `human_feedback`: Optional string containing any comments. +- `updated_action`: Optional string if the action was modified. + +**Response:** +- `status`: A confirmation message indicating the approval result. **Flow:** +1. Validates header and extracts `user_principal_id` as `user_id`. +2. Initializes runtime and context for the session. +3. Sends the `HumanFeedback` approval message to the `GroupChatManager`. +4. If `step_id` is provided, approves the specific step; otherwise, approves all steps. +5. Returns the `status` message indicating the result of the approval. + +### /plans + +**Method:** GET +**Description:** Retrieves all plans for the current user or the plan for a specific session. + +**Request Headers:** + +- `user_principal_id`: User ID (`user_id`) extracted from the authentication header. -1. Initializes runtime and context for the session. -2. Sends the `HumanFeedback` message to the `HumanAgent`. +**Query Parameters:** +- `session_id` (optional): Retrieve the plan for this specific session ID. If not provided, all plans for the user are retrieved. -### /get_latest_plan_by_session/{session_id} +**Response:** +- A list of plans with their details: + - `id`: Unique ID of the plan. + - `session_id`: The session ID associated with the plan. + - `initial_goal`: The initial goal derived from the user's input. + - `overall_status`: The status of the plan (e.g., in_progress, completed, failed). + - `steps`: A list of steps associated with the plan, each including: + - `id`: Unique ID of the step. + - `plan_id`: ID of the plan the step belongs to. + - `action`: The action to be performed. + - `agent`: The agent responsible for the step. + - `status`: The status of the step (e.g., planned, approved, completed). + - `agent_reply`: Optional response from the agent after execution. + - `human_feedback`: Optional feedback provided by the user. + - `updated_action`: Optional modified action based on feedback. + +**Flow:** +1. Validates header and extracts `user_principal_id` as `user_id`. +2. If `session_id` is provided: + - Retrieves the plan for the specified session ID. + - Fetches the steps for the plan. +3. If `session_id` is not provided: + - Retrieves all plans for the user. + - Fetches the steps for each plan concurrently. +4. Returns the plan(s) along with their steps. + +### /steps/{plan_id} **Method:** GET -**Description:** Retrieves the plan associated with a specific session. -**Response:** List of `Plan` objects. +**Description:** Retrieves all steps associated with a specific plan. + +**Request Headers:** + +- `user_principal_id`: User ID (`user_id`) extracted from the authentication header. + +**Path Parameters:** +- `plan_id`: The ID of the plan to retrieve steps for. + +**Response:** +- A list of steps with their details: + - `id`: Unique ID of the step. + - `plan_id`: The ID of the plan the step belongs to. + - `action`: The action to be performed. + - `agent`: The agent responsible for the step. + - `status`: The status of the step (e.g., planned, approved, completed). + - `agent_reply`: Optional response from the agent after execution. + - `human_feedback`: Optional feedback provided by the user. + - `updated_action`: Optional modified action based on feedback. + +**Flow:** +1. Validates header and extracts `user_principal_id` as `user_id`. +2. Retrieves the steps for the specified `plan_id`. +3. Returns the list of steps with their details. -### /get_steps_by_plan/{plan_id} +### /agent_messages/{session_id} **Method:** GET -**Description:** Retrieves the steps associated with a specific plan. -**Response:** List of `Step` objects. +**Description:** Retrieves all agent messages for a specific session. -### /delete_all_messages +**Request Headers:** +- `user_principal_id`: User ID (`user_id`) extracted from the authentication header. + +**Path Parameters:** +- `session_id`: The ID of the session to retrieve agent messages for. + +**Response:** +- A list of agent messages with their details: + - `id`: Unique ID of the agent message. + - `session_id`: The session ID associated with the message. + - `plan_id`: The ID of the plan related to the agent message. + - `content`: The content of the message. + - `source`: The source of the message (e.g., agent type). + - `ts`: The timestamp of the message. + - `step_id`: Optional step ID associated with the message. + +**Flow:** +1. Validates header and extracts `user_principal_id` as `user_id`. +2. Retrieves the agent messages for the specified `session_id`. +3. Returns the list of agent messages with their details. + +### /messages **Method:** DELETE -**Description:** Deletes all messages across sessions (use with caution). -**Response:** Confirmation of deletion. +**Description:** Deletes all messages across sessions. + +**Request Headers:** + +- `user_principal_id`: User ID (`user_id`) extracted from the authentication header. -## Data Types and Models +**Response:** +- A confirmation message: + - `status`: A status message indicating all messages were deleted. -### Messages +**Flow:** +1. Validates header and extracts `user_principal_id` as `user_id`. +2. Deletes all messages across sessions, including: + - Plans + - Sessions + - Steps + - Agent messages +3. Returns a confirmation `status` message. -#### InputTask +### /messages -Represents the initial task input from the user. +**Method:** GET +**Description:** Retrieves all messages across sessions. -**Fields:** +**Request Headers:** -- `session_id`: The session ID. Generated if not provided. -- `description`: The description of the task. +- `user_principal_id`: User ID (`user_id`) extracted from the authentication header. -#### Plan +**Response:** +- A list of all messages with their details: + - `id`: Unique ID of the message. + - `data_type`: The type of the message (e.g., session, step, plan, agent_message). + - `session_id`: The session ID associated with the message. + - `content`: The content of the message. + - `ts`: The timestamp of the message. -Represents a plan containing multiple steps to accomplish the task. +**Flow:** +1. Validates header and extracts `user_principal_id` as `user_id`. +2. Retrieves all messages across sessions. +3. Returns the list of messages with their details. -**Fields:** +### /api/agent-tools -- `id`: Unique ID of the plan. -- `session_id`: The session ID. -- `initial_goal`: The initial goal derived from the user's input. -- `overall_status`: Status of the plan (in_progress, completed, failed). -- `source`: Origin of the plan (e.g., PlannerAgent). +**Method:** GET +**Description:** Retrieves all available agent tools and their descriptions. -#### Step +**Response:** +- A list of agent tools with their details: + - `agent`: The name of the agent associated with the tool. + - `function`: The name of the tool function. + - `description`: A detailed description of what the tool does. + - `arguments`: The arguments required by the tool function. -Represents an individual step within a plan. +**Flow:** +1. Retrieves all agent tools and their metadata. +2. Returns the list of agent tools with their details. + + +## Models and Datatypes +### Models +#### **`BaseDataModel`** +The `BaseDataModel` is a foundational class for creating structured data models using Pydantic. It provides the following attributes: + +- **`id`**: A unique identifier for the data, generated using `uuid`. +- **`ts`**: An optional timestamp indicating when the model instance was created or modified. + +#### **`AgentMessage`** +The `AgentMessage` model represents communication between agents and includes the following fields: + +- **`id`**: A unique identifier for the message, generated using `uuid`. +- **`data_type`**: A literal value of `"agent_message"` to identify the message type. +- **`session_id`**: The session associated with this message. +- **`user_id`**: The ID of the user associated with this message. +- **`plan_id`**: The ID of the related plan. +- **`content`**: The content of the message. +- **`source`**: The origin or sender of the message (e.g., an agent). +- **`ts`**: An optional timestamp for when the message was created. +- **`step_id`**: An optional ID of the step associated with this message. + +#### **`Session`** +The `Session` model represents a user session and extends the `BaseDataModel`. It has the following attributes: + +- **`data_type`**: A literal value of `"session"` to identify the type of data. +- **`current_status`**: The current status of the session (e.g., `active`, `completed`). +- **`message_to_user`**: An optional field to store any messages sent to the user. +- **`ts`**: An optional timestamp for the session's creation or last update. + + +#### **`Plan`** +The `Plan` model represents a high-level structure for organizing actions or tasks. It extends the `BaseDataModel` and includes the following attributes: + +- **`data_type`**: A literal value of `"plan"` to identify the data type. +- **`session_id`**: The ID of the session associated with this plan. +- **`initial_goal`**: A description of the initial goal derived from the user’s input. +- **`overall_status`**: The overall status of the plan (e.g., `in_progress`, `completed`, `failed`). + +#### **`Step`** +The `Step` model represents a discrete action or task within a plan. It extends the `BaseDataModel` and includes the following attributes: + +- **`data_type`**: A literal value of `"step"` to identify the data type. +- **`plan_id`**: The ID of the plan the step belongs to. +- **`action`**: The specific action or task to be performed. +- **`agent`**: The name of the agent responsible for executing the step. +- **`status`**: The status of the step (e.g., `planned`, `approved`, `completed`). +- **`agent_reply`**: An optional response from the agent after executing the step. +- **`human_feedback`**: Optional feedback provided by a user about the step. +- **`updated_action`**: Optional modified action based on human feedback. +- **`session_id`**: The session ID associated with the step. +- **`user_id`**: The ID of the user providing feedback or interacting with the step. + +#### **`PlanWithSteps`** +The `PlanWithSteps` model extends the `Plan` model and includes additional information about the steps in the plan. It has the following attributes: + +- **`steps`**: A list of `Step` objects associated with the plan. +- **`total_steps`**: The total number of steps in the plan. +- **`completed_steps`**: The number of steps that have been completed. +- **`pending_steps`**: The number of steps that are pending approval or completion. + +**Additional Features**: +The `PlanWithSteps` model provides methods to update step counts: +- `update_step_counts()`: Calculates and updates the `total_steps`, `completed_steps`, and `pending_steps` fields based on the associated steps. + +#### **`InputTask`** +The `InputTask` model represents the user’s initial input for creating a plan. It includes the following attributes: + +- **`session_id`**: An optional string for the session ID. If not provided, a new UUID will be generated. +- **`description`**: A string describing the task or goal the user wants to accomplish. +- **`user_id`**: The ID of the user providing the input. + +#### **`ApprovalRequest`** +The `ApprovalRequest` model represents a request to approve a step or multiple steps. It includes the following attributes: + +- **`step_id`**: An optional string representing the specific step to approve. If not provided, the request applies to all steps. +- **`plan_id`**: The ID of the plan containing the step(s) to approve. +- **`session_id`**: The ID of the session associated with the approval request. +- **`approved`**: A boolean indicating whether the step(s) are approved. +- **`human_feedback`**: An optional string containing comments or feedback from the user. +- **`updated_action`**: An optional string representing a modified action based on feedback. +- **`user_id`**: The ID of the user making the approval request. -**Fields:** -- `id`: Unique ID of the step. -- `plan_id`: ID of the plan the step belongs to. -- `action`: The action to be performed. -- `agent`: The agent responsible for the step. -- `status`: Status of the step (e.g., planned, approved, completed). -- `agent_reply`: The response from the agent after executing the action. -- `human_feedback`: Any feedback provided by the human. -- `updated_action`: If the action was modified by human feedback. -- `session_id`: The session ID. +#### **`HumanFeedback`** +The `HumanFeedback` model captures user feedback on a specific step or plan. It includes the following attributes: + +- **`step_id`**: The ID of the step the feedback is related to. +- **`plan_id`**: The ID of the plan containing the step. +- **`session_id`**: The session ID associated with the feedback. +- **`approved`**: A boolean indicating if the step is approved. +- **`human_feedback`**: Optional comments or feedback provided by the user. +- **`updated_action`**: Optional modified action based on the feedback. +- **`user_id`**: The ID of the user providing the feedback. -#### HumanFeedback +#### **`HumanClarification`** +The `HumanClarification` model represents clarifications provided by the user about a plan. It includes the following attributes: -Contains human feedback on a step, such as approval or rejection. +- **`plan_id`**: The ID of the plan requiring clarification. +- **`session_id`**: The session ID associated with the plan. +- **`human_clarification`**: The clarification details provided by the user. +- **`user_id`**: The ID of the user providing the clarification. -**Fields:** +#### **`ActionRequest`** +The `ActionRequest` model captures a request to perform an action within the system. It includes the following attributes: -- `step_id`: ID of the step the feedback is about. -- `plan_id`: ID of the plan. -- `session_id`: The session ID. -- `approved`: Boolean indicating approval. -- `human_feedback`: Optional comments. -- `updated_action`: Optional modified action. +- **`session_id`**: The session ID associated with the action request. +- **`plan_id`**: The ID of the plan associated with the action. +- **`step_id`**: Optional ID of the step associated with the action. +- **`action`**: A string describing the action to be performed. +- **`user_id`**: The ID of the user requesting the action. -#### ApprovalRequest +#### **`ActionResponse`** +The `ActionResponse` model represents the response to an action request. It includes the following attributes: -Sent to the HumanAgent to request approval for a step. +- **`status`**: A string indicating the status of the action (e.g., `success`, `failure`). +- **`message`**: An optional string providing additional details or context about the action's result. +- **`data`**: Optional data payload containing any relevant information from the action. +- **`user_id`**: The ID of the user associated with the action response. -**Fields:** +#### **`PlanStateUpdate`** +The `PlanStateUpdate` model represents an update to the state of a plan. It includes the following attributes: -- `step_id`: ID of the step. -- `plan_id`: ID of the plan. -- `session_id`: The session ID. -- `action`: The action to be approved. -- `agent`: The agent responsible for the action. +- **`plan_id`**: The ID of the plan being updated. +- **`session_id`**: The session ID associated with the plan. +- **`new_state`**: A string representing the new state of the plan (e.g., `in_progress`, `completed`, `failed`). +- **`user_id`**: The ID of the user making the state update. +- **`timestamp`**: An optional timestamp indicating when the update was made. -#### ActionRequest +--- -Sent to specialized agents to perform an action. +#### **`GroupChatMessage`** +The `GroupChatMessage` model represents a message sent in a group chat context. It includes the following attributes: -**Fields:** +- **`message_id`**: A unique ID for the message. +- **`session_id`**: The session ID associated with the group chat. +- **`user_id`**: The ID of the user sending the message. +- **`content`**: The text content of the message. +- **`timestamp`**: A timestamp indicating when the message was sent. -- `step_id`: ID of the step. -- `plan_id`: ID of the plan. -- `session_id`: The session ID. -- `action`: The action to be performed. -- `agent`: The agent that should perform the action. +--- -#### ActionResponse +#### **`RequestToSpeak`** +The `RequestToSpeak` model represents a user's request to speak or take action in a group chat or collaboration session. It includes the following attributes: -Contains the response from an agent after performing an action. +- **`request_id`**: A unique ID for the request. +- **`session_id`**: The session ID associated with the request. +- **`user_id`**: The ID of the user making the request. +- **`reason`**: A string describing the reason or purpose of the request. +- **`timestamp`**: A timestamp indicating when the request was made. -**Fields:** -- `step_id`: ID of the step. -- `plan_id`: ID of the plan. -- `session_id`: The session ID. -- `result`: The result of the action. -- `status`: Status of the step (completed, failed). +### Data Types + +#### **`DataType`** +The `DataType` enumeration defines the types of data used in the system. Possible values include: +- **`plan`**: Represents a plan data type. +- **`session`**: Represents a session data type. +- **`step`**: Represents a step data type. +- **`agent_message`**: Represents an agent message data type. + +--- + +#### **`BAgentType`** +The `BAgentType` enumeration defines the types of agents in the system. Possible values include: +- **`human`**: Represents a human agent. +- **`ai_assistant`**: Represents an AI assistant agent. +- **`external_service`**: Represents an external service agent. -### Agents +#### **`StepStatus`** +The `StepStatus` enumeration defines the possible statuses for a step. Possible values include: +- **`planned`**: Indicates the step is planned but not yet approved or completed. +- **`approved`**: Indicates the step has been approved. +- **`completed`**: Indicates the step has been completed. +- **`failed`**: Indicates the step has failed. -#### Agent Types: -- GroupChatManager -- PlannerAgent -- HumanAgent -- HrAgent -- LegalAgent -- MarketingAgent -- ProcurementAgent -- ProductAgent -- TechSupportAgent +#### **`PlanStatus`** +The `PlanStatus` enumeration defines the possible statuses for a plan. Possible values include: +- **`in_progress`**: Indicates the plan is currently in progress. +- **`completed`**: Indicates the plan has been successfully completed. +- **`failed`**: Indicates the plan has failed. -## Application Flow -### Initialization +#### **`HumanFeedbackStatus`** +The `HumanFeedbackStatus` enumeration defines the possible statuses for human feedback. Possible values include: +- **`pending`**: Indicates the feedback is awaiting review or action. +- **`addressed`**: Indicates the feedback has been addressed. +- **`rejected`**: Indicates the feedback has been rejected. + + +### Application Flow + +#### **Initialization** The initialization process sets up the necessary agents and context for a session. This involves: -- Generating unique AgentIds that include the `session_id` to ensure uniqueness per session. -- Instantiating agents and registering them with the runtime. -- Setting up the Azure OpenAI Chat Completion Client for LLM interactions. -- Creating a `CosmosBufferedChatCompletionContext` for stateful storage. +- **Generating Unique AgentIds**: Each agent is assigned a unique `AgentId` based on the `session_id`, ensuring that multiple sessions can operate independently. +- **Instantiating Agents**: Various agents, such as `PlannerAgent`, `HrAgent`, and `GroupChatManager`, are initialized and registered with unique `AgentIds`. +- **Setting Up Azure OpenAI Client**: The Azure OpenAI Chat Completion Client is initialized to handle LLM interactions with support for function calling, JSON output, and vision handling. +- **Creating Cosmos DB Context**: A `CosmosBufferedChatCompletionContext` is established for stateful interaction storage. **Code Reference: `utils.py`** - async def initialize(session_id: Optional[str] = None) -> Tuple[SingleThreadedAgentRuntime, CosmosBufferedChatCompletionContext]: - # Generate session_id if not provided - # Check if session already initialized - # Initialize agents with unique AgentIds - # Create Cosmos DB context - # Register tool agents and specialized agents - # Start the runtime +**Steps:** +1. **Session ID Generation**: If `session_id` is not provided, a new UUID is generated. +2. **Agent Registration**: Each agent is assigned a unique `AgentId` and registered with the runtime. +3. **Azure OpenAI Initialization**: The LLM client is configured for advanced interactions. +4. **Cosmos DB Context Creation**: A buffered context is created for storing stateful interactions. +5. **Runtime Start**: The runtime is started, enabling communication and agent operation. + + ### Input Task Handling diff --git a/src/backend/app.py b/src/backend/app.py index a4f609c3..a5ba33c8 100644 --- a/src/backend/app.py +++ b/src/backend/app.py @@ -57,13 +57,50 @@ @app.post("/input_task") async def input_task_endpoint(input_task: InputTask, request: Request): """ - Endpoint to receive the initial input task from the user. - - Args: - input_task (InputTask): The input task containing the session ID and description. - - Returns: - dict: Status message, session ID, and plan ID. + Receive the initial input task from the user. + + --- + tags: + - Input Task + parameters: + - name: user_principal_id + in: header + type: string + required: true + description: User ID extracted from the authentication header + - name: body + in: body + required: true + schema: + type: object + properties: + session_id: + type: string + description: Optional session ID, generated if not provided + description: + type: string + description: The task description + user_id: + type: string + description: The user ID associated with the task + responses: + 200: + description: Task created successfully + schema: + type: object + properties: + status: + type: string + session_id: + type: string + plan_id: + type: string + description: + type: string + user_id: + type: string + 400: + description: Missing or invalid user information """ if not rai_success(input_task.description): @@ -98,21 +135,58 @@ async def input_task_endpoint(input_task: InputTask, request: Request): @app.post("/human_feedback") async def human_feedback_endpoint(human_feedback: HumanFeedback, request: Request): """ - Endpoint to receive human feedback on a step. - - Args: - human_feedback (HumanFeedback): The human feedback message. - - class HumanFeedback(BaseModel): - step_id: str - plan_id: str - session_id: str - approved: bool - human_feedback: Optional[str] = None - updated_action: Optional[str] = None - - Returns: - dict: Status message and session ID. + Receive human feedback on a step. + + --- + tags: + - Feedback + parameters: + - name: user_principal_id + in: header + type: string + required: true + description: User ID extracted from the authentication header + - name: body + in: body + required: true + schema: + type: object + properties: + step_id: + type: string + description: The ID of the step to provide feedback for + plan_id: + type: string + description: The plan ID + session_id: + type: string + description: The session ID + approved: + type: boolean + description: Whether the step is approved + human_feedback: + type: string + description: Optional feedback details + updated_action: + type: string + description: Optional updated action + user_id: + type: string + description: The user ID providing the feedback + responses: + 200: + description: Feedback received successfully + schema: + type: object + properties: + status: + type: string + session_id: + type: string + step_id: + type: string + 400: + description: Missing or invalid user information """ authenticated_user = get_authenticated_user_details( request_headers=request.headers @@ -136,18 +210,47 @@ class HumanFeedback(BaseModel): @app.post("/human_clarification_on_plan") async def human_clarification_endpoint(human_clarification: HumanClarification, request: Request): """ - Endpoint to receive human clarification on the plan. - - Args: - human_clarification (HumanClarification): The human clarification message. - - class HumanFeedback(BaseModel): - plan_id: str - session_id: str - human_clarification: str - - Returns: - dict: Status message and session ID. + Receive human clarification on a plan. + + --- + tags: + - Clarification + parameters: + - name: user_principal_id + in: header + type: string + required: true + description: User ID extracted from the authentication header + - name: body + in: body + required: true + schema: + type: object + properties: + plan_id: + type: string + description: The plan ID requiring clarification + session_id: + type: string + description: The session ID + human_clarification: + type: string + description: Clarification details provided by the user + user_id: + type: string + description: The user ID providing the clarification + responses: + 200: + description: Clarification received successfully + schema: + type: object + properties: + status: + type: string + session_id: + type: string + 400: + description: Missing or invalid user information """ authenticated_user = get_authenticated_user_details( request_headers=request.headers @@ -170,7 +273,54 @@ class HumanFeedback(BaseModel): @app.post("/approve_step_or_steps") async def approve_step_endpoint(human_feedback: HumanFeedback, request: Request) -> dict[str, str]: """ - Endpoint to approve a step if step_id is provided, otherwise approve all the steps. + Approve a step or multiple steps in a plan. + + --- + tags: + - Approval + parameters: + - name: user_principal_id + in: header + type: string + required: true + description: User ID extracted from the authentication header + - name: body + in: body + required: true + schema: + type: object + properties: + step_id: + type: string + description: Optional step ID to approve + plan_id: + type: string + description: The plan ID + session_id: + type: string + description: The session ID + approved: + type: boolean + description: Whether the step(s) are approved + human_feedback: + type: string + description: Optional feedback details + updated_action: + type: string + description: Optional updated action + user_id: + type: string + description: The user ID providing the approval + responses: + 200: + description: Approval status returned + schema: + type: object + properties: + status: + type: string + 400: + description: Missing or invalid user information """ authenticated_user = get_authenticated_user_details( request_headers=request.headers @@ -201,14 +351,61 @@ async def approve_step_endpoint(human_feedback: HumanFeedback, request: Request) @app.get("/plans", response_model=List[PlanWithSteps]) async def get_plans(request: Request, session_id: Optional[str] = Query(None)) -> List[PlanWithSteps]: """ - Endpoint to retrieve plans. If session_id is provided, retrieve the plan for that session. - Otherwise, retrieve all plans. - - Args: - session_id (Optional[str]): The session ID. - - Returns: - List[Plan]: The list of plans. + Retrieve plans for the current user. + + --- + tags: + - Plans + parameters: + - name: session_id + in: query + type: string + required: false + description: Optional session ID to retrieve plans for a specific session + responses: + 200: + description: List of plans with steps for the user + schema: + type: array + items: + type: object + properties: + id: + type: string + description: Unique ID of the plan + session_id: + type: string + description: Session ID associated with the plan + initial_goal: + type: string + description: The initial goal derived from the user's input + overall_status: + type: string + description: Status of the plan (e.g., in_progress, completed) + steps: + type: array + items: + type: object + properties: + id: + type: string + description: Unique ID of the step + plan_id: + type: string + description: ID of the plan the step belongs to + action: + type: string + description: The action to be performed + agent: + type: string + description: The agent responsible for the step + status: + type: string + description: Status of the step (e.g., planned, approved, completed) + 400: + description: Missing or invalid user information + 404: + description: Plan not found """ authenticated_user = get_authenticated_user_details( request_headers=request.headers @@ -247,13 +444,53 @@ async def get_plans(request: Request, session_id: Optional[str] = Query(None)) - @app.get("/steps/{plan_id}", response_model=List[Step]) async def get_steps_by_plan(plan_id: str, request: Request) -> List[Step]: """ - Endpoint to retrieve steps for a specific plan. - - Args: - plan_id (str): The plan ID. - - Returns: - List[Step]: The list of steps. + Retrieve steps for a specific plan. + + --- + tags: + - Steps + parameters: + - name: plan_id + in: path + type: string + required: true + description: The ID of the plan to retrieve steps for + responses: + 200: + description: List of steps associated with the specified plan + schema: + type: array + items: + type: object + properties: + id: + type: string + description: Unique ID of the step + plan_id: + type: string + description: ID of the plan the step belongs to + action: + type: string + description: The action to be performed + agent: + type: string + description: The agent responsible for the step + status: + type: string + description: Status of the step (e.g., planned, approved, completed) + agent_reply: + type: string + description: Optional response from the agent after execution + human_feedback: + type: string + description: Optional feedback provided by a human + updated_action: + type: string + description: Optional modified action based on feedback + 400: + description: Missing or invalid user information + 404: + description: Plan or steps not found """ authenticated_user = get_authenticated_user_details( request_headers=request.headers @@ -269,13 +506,50 @@ async def get_steps_by_plan(plan_id: str, request: Request) -> List[Step]: @app.get("/agent_messages/{session_id}", response_model=List[AgentMessage]) async def get_agent_messages(session_id: str, request: Request) -> List[AgentMessage]: """ - Endpoint to retrieve agent messages for a specific session. - - Args: - session_id (str): The session ID. - - Returns: - List[AgentMessage]: The list of agent messages. + Retrieve agent messages for a specific session. + + --- + tags: + - Agent Messages + parameters: + - name: session_id + in: path + type: string + required: true + description: The ID of the session to retrieve agent messages for + responses: + 200: + description: List of agent messages associated with the specified session + schema: + type: array + items: + type: object + properties: + id: + type: string + description: Unique ID of the agent message + session_id: + type: string + description: Session ID associated with the message + plan_id: + type: string + description: Plan ID related to the agent message + content: + type: string + description: Content of the message + source: + type: string + description: Source of the message (e.g., agent type) + ts: + type: integer + description: Timestamp of the message + step_id: + type: string + description: Optional step ID associated with the message + 400: + description: Missing or invalid user information + 404: + description: Agent messages not found """ authenticated_user = get_authenticated_user_details( request_headers=request.headers @@ -291,10 +565,22 @@ async def get_agent_messages(session_id: str, request: Request) -> List[AgentMes @app.delete("/messages") async def delete_all_messages(request: Request) -> dict[str, str]: """ - Endpoint to delete all messages across sessions. - - Returns: - dict: Confirmation of deletion. + Delete all messages across sessions. + + --- + tags: + - Messages + responses: + 200: + description: Confirmation of deletion + schema: + type: object + properties: + status: + type: string + description: Status message indicating all messages were deleted + 400: + description: Missing or invalid user information """ authenticated_user = get_authenticated_user_details( request_headers=request.headers @@ -317,10 +603,39 @@ async def delete_all_messages(request: Request) -> dict[str, str]: @app.get("/messages") async def get_all_messages(request: Request): """ - Endpoint to retrieve all messages. - - Returns: - List[dict]: The list of message dictionaries. + Retrieve all messages across sessions. + + --- + tags: + - Messages + responses: + 200: + description: List of all messages across sessions + schema: + type: array + items: + type: object + properties: + id: + type: string + description: Unique ID of the message + data_type: + type: string + description: Type of the message (e.g., session, step, plan, agent_message) + session_id: + type: string + description: Session ID associated with the message + user_id: + type: string + description: User ID associated with the message + content: + type: string + description: Content of the message + ts: + type: integer + description: Timestamp of the message + 400: + description: Missing or invalid user information """ authenticated_user = get_authenticated_user_details( request_headers=request.headers @@ -335,6 +650,33 @@ async def get_all_messages(request: Request): @app.get("/api/agent-tools") async def get_agent_tools(): + """ + Retrieve all available agent tools. + + --- + tags: + - Agent Tools + responses: + 200: + description: List of all available agent tools and their descriptions + schema: + type: array + items: + type: object + properties: + agent: + type: string + description: Name of the agent associated with the tool + function: + type: string + description: Name of the tool function + description: + type: string + description: Detailed description of what the tool does + arguments: + type: string + description: Arguments required by the tool function + """ return retrieve_all_agent_tools()