agent.py

Overview

The agent.py file defines the Agent class, a central entity in the InfiniFlow system responsible for managing conversational agents. An Agent encapsulates properties such as identity, avatar, description, and an embedded Domain-Specific Language (DSL) representation used to structure workflows or dialogue flows. The file also includes the nested Agent.Dsl class, which models the internal DSL structure, including components, graph nodes, edges, and messaging/history tracking.

Key functionalities provided by the Agent class include session management capabilities such as creating, listing, and deleting sessions associated with the agent. These sessions represent individual interaction instances with the agent.

This file interacts primarily with the Session class (imported from .session) to handle session lifecycle operations, and inherits from a base class Base (imported from .base) which likely provides foundational HTTP request methods (get, post, rm) and shared utilities.

Classes and Methods

Class: Agent

Agent represents a conversational or workflow agent in the InfiniFlow system.

Constructor: __init__(self, rag, res_dict)

Initializes an Agent instance.

• Parameters:

  • rag: Reference to the parent RAG (Retrieval-Augmented Generation) controller or context object. Used for internal API requests and resource management.

  • res_dict: A dictionary containing initial data for the agent, potentially including id, avatar, canvas_type, description, and dsl information.

• Attributes initialized:

  • id (str or None): Unique identifier of the agent.

  • avatar (str or None): Avatar image or icon for the agent.

  • canvas_type (str or None): Type of canvas or visual interaction model used.

  • description (str or None): Text description of the agent.

  • dsl (Agent.Dsl or None): Embedded domain-specific language instance representing the agent's workflow logic.

• Usage example:

  agent = Agent(rag_instance, agent_data_dict)
  

Nested Class: Agent.Dsl

Represents the Domain-Specific Language (DSL) structure embedded within an Agent. This encapsulates the components, graph structure, message history, and references used to define the agent's operational logic.

Constructor: __init__(self, rag, res_dict)

Initializes the DSL structure with default or provided data.

• Parameters:

  • rag: Reference to the RAG controller/context.

  • res_dict: Dictionary containing DSL initialization data (optional).

• Attributes:

  • answer (list): List to store answers or output generated.

  • components (dict): Components of the DSL graph keyed by component name. Initialized with a default "begin" component.

  • graph (dict): Graph structure containing nodes and edges dicts representing the flow diagram.

  • history (list): Stores historical states or actions.

  • messages (list): Messages exchanged or logged during agent execution.

  • path (list): Execution path trace.

  • reference (list): External or internal references aiding DSL execution.

• Usage example:

  dsl = Agent.Dsl(rag_instance, dsl_data)
  

Method: create_session(self, **kwargs) -> Session

Creates a new session for the agent.

• Parameters:
  Accepts arbitrary keyword arguments (**kwargs) that define session creation parameters (e.g., user info, session context).

• Returns:
  A Session object representing the newly created session.

• Raises:
  An Exception if the API response code is not zero (indicating failure).

• Implementation details:
  Sends a POST request to the endpoint /agents/{agent_id}/sessions with JSON payload kwargs. On success, instantiates and returns a Session object.

• Usage example:

  session = agent.create_session(user_id="123", metadata={"topic": "support"})
  

Method: list_sessions(self, page: int = 1, page_size: int = 30, orderby: str = "create_time", desc: bool = True, id: str = None) -> list[Session]

Lists sessions associated with the agent, supporting pagination and sorting.

• Parameters:

  • page (int): Page number to retrieve (default: 1).

  • page_size (int): Number of sessions per page (default: 30).

  • orderby (str): Field to sort by (default: "create_time").

  • desc (bool): Whether to sort descending (default: True).

  • id (str or None): Optional filter to list a specific session by ID.

• Returns:
  A list of Session objects.

• Raises:
  An Exception if the API response code is not zero.

• Implementation details:
  Sends a GET request to /agents/{agent_id}/sessions with query parameters. Parses the JSON response and converts each session entry into a Session object.

• Usage example:

  sessions = agent.list_sessions(page=2, page_size=10)
  for session in sessions:
      print(session.id, session.status)
  

Method: delete_sessions(self, ids: list[str] | None = None)

Deletes one or more sessions by their IDs.

• Parameters:

  • ids (list of str or None): List of session IDs to delete. If None, behavior depends on backend implementation (likely no action).

• Returns:
  None.

• Raises:
  An Exception if the API response code is not zero.

• Implementation details:
  Sends a DELETE (rm) request to /agents/{agent_id}/sessions with the list of IDs. Checks the response for success.

• Usage example:

  agent.delete_sessions(ids=["session1", "session2"])
  

Important Implementation Details

• The Agent class extends from Base, inheriting HTTP methods (get, post, rm) that abstract API communication.

• The Agent.Dsl nested class is initialized with a default graph containing a single "begin" node, establishing a starting point for workflows or dialogue graphs.

• API responses are expected to follow a standard format with a code field indicating success (0 means success).

• Session management methods tightly couple with RESTful endpoints structured under /agents/{agent_id}/sessions.

• Exception handling is rudimentary — any non-zero response code raises a generic Exception with the server-provided message.

Interaction with Other System Components

• Base class (base.Base): Provides shared infrastructure such as HTTP request handling, error management, and possibly logging.

• Session class (session.Session): Represents individual agent interaction sessions; tightly coupled with Agent for session lifecycle management.

• RAG controller/context (rag parameter): Passed throughout to maintain context and possibly shared resources like authentication tokens or configuration.

The Agent class acts as a gateway to managing conversational workflows and their sessions, serving as an interface between user-facing components and backend session management systems.

Visual Diagram

classDiagram
    class Agent {
        -id: str
        -avatar: str
        -canvas_type: str
        -description: str
        -dsl: Agent.Dsl
        +__init__(rag, res_dict)
        +create_session(**kwargs) Session
        +list_sessions(page:int, page_size:int, orderby:str, desc:bool, id:str) list~Session~
        +delete_sessions(ids: list~str~| None)
    }

    class Agent.Dsl {
        -answer: list
        -components: dict
        -graph: dict
        -history: list
        -messages: list
        -path: list
        -reference: list
        +__init__(rag, res_dict)
    }

    class Base {
        <<abstract>>
        +get()
        +post()
        +rm()
    }

    class Session {
        +__init__(rag, data)
    }

    Agent ..|> Base
    Agent.Dsl ..|> Base
    Agent --> Session : uses

Summary

The agent.py file provides a well-structured Agent class that models agents within the InfiniFlow platform, focusing on managing agent identity, embedded DSL workflows, and session lifecycle. It uses RESTful API calls inherited from a base class to manage sessions, encapsulating the complexity behind simple method calls. The nested Dsl class models the agent's internal workflow structure, designed for extensibility and interaction modeling.

This file is a critical component connecting the agent's representation with backend session management and workflow execution, enabling higher-level conversational or workflow orchestration in the InfiniFlow system.