agp_api.gateway package — agp_api 0.0.2 documentation

# agp_api.gateway package

## Submodules

## agp_api.gateway.gateway_container module

Module gateway_holder: Contains the GatewayHolder class for managing the Gateway instance and FastAPI app.

class agp_api.gateway.gateway_container.GatewayContainer

  Bases: `object`

  A container class for managing the Gateway instance and FastAPI app.

  This class serves as a central point for handling the Gateway instance and the FastAPI application. It facilitates the reception of packets from the Agent Gateway Protocol (AGP) and reinjects them into the FastAPI application for further processing.

  gateway

    An instance of the Gateway that this container encapsulates.

    Type:

      Gateway

  fastapi_app

    An instance of the FastAPI application used to process incoming packets from the AGP.

    Type:

      Optional[FastAPI]

  __init__(gateway=None, fastapi_app=None)

    Initializes the GatewayContainer with a Gateway instance and optionally a FastAPI app.

    Parameters:

      - gateway (Optional[Gateway]) – The Gateway instance to manage. If not provided, a new instance will be created.

      - fastapi_app (Optional[FastAPI]) – The FastAPI application instance.

  async connect_with_retry(agent_container, max_duration=300, initial_delay=1, remote_agent=None)

    Attempts to connect to a gateway at the specified address and port using exponential backoff. This asynchronous function repeatedly tries to establish a connection by calling the connect_to_gateway function. If a connection attempt fails, it logs a warning and waits for a period that doubles after each failure (capped at 30 seconds) until a successful connection is made or until the accumulated time exceeds max_duration. :param address: The hostname or IP address of the gateway. :type address: str :param port: The port number to connect to. :type port: int :param max_duration: Maximum duration (in seconds) to attempt the connection. Default is 300. :type max_duration: int, optional :param initial_delay: Initial delay (in seconds) before the first retry. Default is 1. :type initial_delay: int, optional

    Returns:

      Returns a tuple containing the source and a message received upon successful connection.

    Return type:

      tuple

    Raises:

      TimeoutError – If the connection is not successfully established within max_duration seconds.

    Parameters:

      - agent_container (AgentContainer)

      - remote_agent (str | None)

  classmethod create_error(error, code, agent_id)

    Creates a reply message with an error code.

    Parameters:

      - error (str) – The error message that will be included in the reply.

      - code (int) – The numerical code representing the error.

      - agent_id (str | None)

    Returns:

      A JSON-formatted string encapsulating the error message and error code.

    Return type:

      str

  create_gateway()

    Creates a new Gateway instance with the provided configuration.

    Returns:

      The newly created Gateway instance.

    Return type:

      Gateway

  get_fastapi_app()

    Returns the stored FastAPI application instance.

    Return type:

      FastAPI | None

  get_gateway()

    Returns the stored Gateway instance.

    Return type:

      Gateway

  process_message(payload)

    Parse and process the incoming payload message.

    This function decodes the incoming payload, validates essential fields, extracts required information, and forwards the request to a FastAPI app. It then returns the server’s response or handles errors appropriately.

    Parameters:

      - payload (dict) – A dictionary containing the message details. Expected keys include:

      - "agent_id" (-) – Identifier for the agent; must be non-empty.

      - "route" (-) – The API route to which the message should be sent.

      - "input" (-) – A dictionary with a key “messages”, which is a non-empty list where each element

      - key. (is a dictionary. The last message in this list should contain the human input under the "content")

      - "metadata" (-) – A dictionary that may contain an “id” for tracking purposes.

    Returns:

      A JSON string representing the reply. This is either the successful response from the FastAPI server when a status code 200 is returned, or a JSON-encoded error message if validation fails.

    Return type:

      str

    Raises:

      - Exception – If the FastAPI server returns a status code other than 200, an exception with the status code

      - and error details is raised. –

  async publish_messsage(message, agent_container, remote_agent)

    Sends a message (JSON string) to the remote endpoint

    Parameters:

      - msg (str) – A JSON string representing the request payload.

      - message (Dict[str, Any])

      - agent_container (AgentContainer)

      - remote_agent (str)

  set_config(endpoint='http://127.0.0.1:46357', insecure=False)

    Sets the configuration for the Gateway instance.

    Parameters:

      - endpoint (str, optional) – The endpoint for the Gateway in the format “http://<hostname_or_ip>:<port>”. Defaults to “http://127.0.0.1:46357”.

      - insecure (bool, optional) – Whether to use an insecure connection. Defaults to False.

    Returns:

      None

    Return type:

      None

  set_fastapi_app(app)

    Sets the FastAPI application instance.

    Parameters:

      app (FastAPI)

    Return type:

      None

  set_gateway(gateway)

    Sets the Gateway instance.

    Parameters:

      gateway (Gateway)

    Return type:

      None

  async start_server(agent_container)

    Asynchronously starts the data plane, which listens for incoming messages from the gateway, processes each message, and sends a reply back to the source agent. The function retrieves necessary agent configuration parameters such as organization, namespace, and local agent information. It then enters an infinite loop, waiting for messages, processing each message with process_message, logging the interaction, and replying to the source. If the asynchronous task is cancelled, it logs a shutdown message and raises a RuntimeError. :returns: A tuple (last_src, last_msg) containing the last received source and the last processed message. :rtype: tuple

    Raises:

      RuntimeError – If the task is cancelled, triggering a shutdown of the data plane.

    Parameters:

      agent_container (AgentContainer)

## Module contents