Scale Agent Factory on a Single Host

Configure Oracle Advanced Queuing (AQ) and multiple ASGI workers to handle concurrent requests in a single-host Agent Factory production deployment.

This feature is supported in Agent Factory release 26.7 and later.

Before You Begin

You need:

• Administrator access to the Agent Factory application database.
• The database user that owns the Agent Factory repository. This topic uses <DB_USER> for that user.
• Access to the host that runs the oracle-applied-ai-label container.
• A chosen maximum ASGI worker count. 8 workers is the recommended baseline value for most single-host deployments; choose a larger value only after sizing the host, database connection pool, Oracle AQ, and downstream model services.

Configure Oracle AQ

Run the following script as a database administrator in the Agent Factory application database. Replace <DB_USER> with the Agent Factory repository user and <MAX_ASGI_WORKERS> with the largest worker count that the deployment will use.

As a general guideline, configure at least 8 subscribers. To support, for example, up to 16 ASGI workers, use 16 for <MAX_ASGI_WORKERS> before starting the application with more than 8 workers. AQ subscribers do not override an Agent Factory worker-count cap; ensure the deployed release and its worker-cap configuration permit the requested count.

GRANT EXECUTE ON SYS.DBMS_AQ TO <DB_USER>;

BEGIN
  DBMS_AQADM.CREATE_QUEUE_TABLE(
    queue_table => '<DB_USER>.AAI_SOCKETIO_QTAB',
    queue_payload_type => 'SYS.AQ$_JMS_TEXT_MESSAGE',
    multiple_consumers => TRUE
  );
EXCEPTION
  WHEN OTHERS THEN
    IF SQLCODE != -24001 THEN
      RAISE;
    END IF;
END;
/

BEGIN
  DBMS_AQADM.CREATE_QUEUE(
    queue_name => '<DB_USER>.AAI_SOCKETIO_QUEUE',
    queue_table => '<DB_USER>.AAI_SOCKETIO_QTAB'
  );
EXCEPTION
  WHEN OTHERS THEN
    IF SQLCODE != -24006 THEN
      RAISE;
    END IF;
END;
/

BEGIN
  DBMS_AQADM.START_QUEUE(
    queue_name => '<DB_USER>.AAI_SOCKETIO_QUEUE'
  );
EXCEPTION
  WHEN OTHERS THEN
    IF SQLCODE != -25207 THEN
      RAISE;
    END IF;
END;
/

BEGIN
  FOR slot_number IN 1..<MAX_ASGI_WORKERS> LOOP
    DECLARE
      subscriber SYS.AQ$_AGENT;
    BEGIN
      subscriber := SYS.AQ$_AGENT('AAI_SIO_' || slot_number, NULL, NULL);
      DBMS_AQADM.ADD_SUBSCRIBER(
        queue_name => '<DB_USER>.AAI_SOCKETIO_QUEUE',
        subscriber => subscriber
      );
    EXCEPTION
      WHEN OTHERS THEN
        IF SQLCODE != -24034 THEN
          RAISE;
        END IF;
    END;
  END LOOP;
END;
/

BEGIN
  DBMS_AQADM.GRANT_QUEUE_PRIVILEGE(
    privilege => 'ENQUEUE',
    queue_name => '<DB_USER>.AAI_SOCKETIO_QUEUE',
    grantee => '<DB_USER>',
    grant_option => FALSE
  );
  DBMS_AQADM.GRANT_QUEUE_PRIVILEGE(
    privilege => 'DEQUEUE',
    queue_name => '<DB_USER>.AAI_SOCKETIO_QUEUE',
    grantee => '<DB_USER>',
    grant_option => FALSE
  );
END;
/

The database administrator needs the AQ administrative privileges required to run DBMS_AQADM. The Agent Factory runtime user requires only EXECUTE ON SYS.DBMS_AQ and the queue ENQUEUE and DEQUEUE privileges granted above.

Enable Concurrency During a Fresh Installation

Use this procedure for a new production installation:

1. In the web installer, enter the database connection details and test the connection.
2. Before you click Install, configure Oracle AQ with a subscriber count at least equal to the worker count you intend to use.
3. Return to the web installer and click Install.
4. The application container starts with multiple ASGI workers. By default, Agent Factory uses the number of available CPUs, up to 8 workers.

Enable Concurrency for an Existing Installation

Use this procedure if Agent Factory is already installed in production mode:

1. Configure Oracle AQ with a subscriber count at least equal to the intended ASGI worker count.
2. Ensure the Agent Factory worker-cap configuration permits the intended count. The packaged default is 8 workers.
3. Set the number of ASGI workers and restart Agent Factory.
4. Verify the number of running workers.

Set the Number of ASGI Workers

Run the following command on the container host. This example configures four ASGI workers and restarts Agent Factory:

podman exec -u root oracle-applied-ai-label bash -c 'export AGENT_FACTORY_ASGI_WORKERS=4; /home/aaiuser/install/agent_factory/manage_app.sh restart all'

Do not set AGENT_FACTORY_ASGI_WORKERS above the number of AQ subscribers that were configured or above the configured Agent Factory worker cap. For example, set AGENT_FACTORY_ASGI_WORKERS=16 only after subscribers AAI_SIO_1 through AAI_SIO_16 have been created and the worker cap permits sixteen workers.

Verify the Number of ASGI Workers

Run the following command on the container host:

podman exec oracle-applied-ai-label bash -c '
master_pid=$(ps -eo pid=,ppid=,args= |
  sed -n "\\|gunicorn_config/uvicorn_config.py| {s/^[[:space:]]*\\([0-9][0-9]*\\)[[:space:]]*1[[:space:]].*/\\1/p;q;}")
if [ -z "$master_pid" ]; then
  echo "ASGI workers: 0 (ASGI Gunicorn master not running)"
else
  worker_count=$(ps -eo ppid= | grep -c "^[[:space:]]*$master_pid[[:space:]]*$")
  echo "ASGI workers: $worker_count"
fi
'