Initial code for Select AI Agents

Author: aosingh

doc/source/conf.py

@@ -56,3 +56,7 @@
 html_static_path = ["_static"]
 
 pygments_style = "sphinx"
+
+latex_elements = {
+    "maxlistdepth": "10",  # Increase the maximum list nesting depth
+}

doc/source/index.rst

@@ -97,3 +97,13 @@ Synthetic Data
     :maxdepth: 3
 
     user_guide/synthetic_data.rst
+
+
+Select AI Agents
+================
+
+.. toctree::
+    :numbered:
+    :maxdepth: 3
+
+    user_guide/agent.rst

doc/source/user_guide/agent.rst

@@ -0,0 +1,249 @@
+.. _agent:
+
+``select_ai.agent`` adds a thin Python layer over Oracle Autonomous Database's
+``DBMS_CLOUD_AI_AGENT`` package so you can define tools, compose tasks, wire up
+agents and run teams from Python using the existing select_ai connection objects
+
+- Keep agent state and orchestration in the database
+
+- Register callable tools (PL/SQL procedure or functions, SQL, external HTTP
+  endpoints, Slack or Email notifications) and attach them to tasks
+
+- Group agents into teams and invoke them with a single API call
+
+
+********
+``Tool``
+********
+
+A callable which Select AI agent can invoke to accomplish a certain task.
+Users can either register built-in tools or create a custom tool using a PL/SQL
+stored procedure.
+
+Supported Tools
++++++++++++++++
+
+Following class methods of ``select_ai.agent.Tool`` class
+can be used to create tools. Invoking them will create a proxy object in the
+Python layer and persist the tool in the Database using
+``DBMS_CLOUD_AI_AGENT.CREATE_TOOL``
+
+
+.. list-table:: Select AI Agent Tools
+    :header-rows: 1
+    :widths: 20 50 30
+    :align: left
+
+    * - Tool Type
+      - Class Method
+      - Arguments
+    * - ``EMAIL``
+      - ``select_ai.agent.Tool.create_email_notification_tool``
+      -  - ``tool_name``
+         - ``credential_name``
+         - ``recipient``
+         - ``sender``
+         - ``smtp_host``
+    * - ``HTTP``
+      - ``select_ai.agent.Tool.create_http_tool``
+      - ``tool_name``, ``credential_name``, ``endpoint``
+    * - ``SQL``
+      - ``select_ai.agent.Tool.create_sql_tool``
+      - ``tool_name``, ``profile_name``
+    * - ``SLACK``
+      - ``select_ai.agent.Tool.create_slack_notification_tool``
+      - ``tool_name``, ``credential_name``, ``slack_channel``
+    * - ``WEBSEARCH``
+      - ``select_ai.agent.Tool.create_websearch_tool``
+      - ``tool_name``, ``credential_name``
+    * - ``PL/SQL custom tool``
+      - ``select_ai.agent.Tool.create_pl_sql_tool``
+      - ``tool_name``, ``function``
+    * - ``RAG``
+      - ``select_ai.agent.Tool.create_rag_tool``
+      - ``tool_name``, ``profile_name``
+
+.. latex:clearpage::
+
+.. autoclass:: select_ai.agent.ToolAttributes
+   :members:
+
+.. autoclass:: select_ai.agent.ToolParams
+   :members:
+
+.. latex:clearpage::
+
+.. autoclass:: select_ai.agent.Tool
+   :members:
+
+.. latex:clearpage::
+
+Create Tool
++++++++++++
+
+The following example shows creation of an AI agent tool to perform natural
+language translation to SQL using an OCI AI profile
+
+.. literalinclude:: ../../../samples/agent/tool_create.py
+   :language: python
+   :lines: 14-
+
+output::
+
+    MOVIE_SQL_TOOL
+
+    ToolAttributes(instruction=None,
+                   function=None,
+                   tool_params=SQLToolParams(_REQUIRED_FIELDS=None,
+                                             credential_name=None,
+                                             endpoint=None,
+                                             notification_type=None,
+                                             profile_name='oci_ai_profile',
+                                             recipient=None,
+                                             sender=None,
+                                             slack_channel=None,
+                                             smtp_host=None),
+                   tool_inputs=None,
+                   tool_type=<ToolType.SQL: 'SQL'>)
+
+
+
+.. latex:clearpage::
+
+
+List Tools
+++++++++++
+
+.. literalinclude:: ../../../samples/agent/tool_list.py
+   :language: python
+   :lines: 14-
+
+output::
+
+    Tool(tool_name=MOVIE_SQL_TOOL, attributes=ToolAttributes(instruction='This tool is used to work with SQL queries using natural language. Input should be a natural language query about data or database operations. The tool behavior depends on the configured action: RUNSQL - generates and executes the SQL query returning actual data; SHOWSQL - generates and displays the SQL statement without executing it; EXPLAINSQL - generates SQL and provides a natural language explanation of what the query does. Always provide clear, specific questions about the data you want to retrieve or analyze.', function='dbms_cloud_ai_agent.sql_tool', tool_params=SQLToolParams(_REQUIRED_FIELDS=None, credential_name=None, endpoint=None, notification_type=None, profile_name='oci_ai_profile', recipient=None, sender=None, slack_channel=None, smtp_host=None), tool_inputs=None, tool_type='SQL'), description=My Select AI MOVIE SQL agent tool)
+
+    Tool(tool_name=LLM_CHAT_TOOL, attributes=ToolAttributes(instruction='This tool is used to work with SQL queries using natural language. Input should be a natural language query about data or database operations. The tool behavior depends on the configured action: RUNSQL - generates and executes the SQL query returning actual data; SHOWSQL - generates and displays the SQL statement without executing it; EXPLAINSQL - generates SQL and provides a natural language explanation of what the query does. Always provide clear, specific questions about the data you want to retrieve or analyze.', function='dbms_cloud_ai_agent.sql_tool', tool_params=SQLToolParams(_REQUIRED_FIELDS=None, credential_name=None, endpoint=None, notification_type=None, profile_name='oci_ai_profile', recipient=None, sender=None, slack_channel=None, smtp_host=None), tool_inputs=None, tool_type='SQL'), description=My Select AI agent tool)
+
+.. latex:clearpage::
+
+********
+``Task``
+********
+
+Each task is identified by a ``task_name`` and includes a set of attributes that
+guide the agent’s behavior during execution.
+Key attributes include the ``instruction``, which describes the task’s purpose and
+provides context for the agent to reason about when and how to use it,
+and the ``tools`` list, which specifies which tools the agent can choose from to
+accomplish the task. An optional ``input`` field allows a task to depend on the
+output of prior tasks, enabling task chaining and multi-step workflows.
+
+.. autoclass:: select_ai.agent.TaskAttributes
+   :members:
+
+.. latex:clearpage::
+
+.. autoclass:: select_ai.agent.Task
+   :members:
+
+.. latex:clearpage::
+
+
+Create Task
++++++++++++
+
+In the following task, we use the ``MOVIE_SQL_TOOL`` created in the
+previous step
+
+.. literalinclude:: ../../../samples/agent/task_create.py
+   :language: python
+
+output::
+
+    ANALYZE_MOVIE_TASK
+
+    TaskAttributes(instruction='Help the user with their request about movies. '
+                               'User question: {query}. You can use SQL tool to '
+                               'search the data from database',
+                   tools=['MOVIE_SQL_TOOL'],
+                   input=None,
+                   enable_human_tool=False)
+
+
+.. latex:clearpage::
+
+List Tasks
++++++++++++
+
+.. literalinclude:: ../../../samples/agent/tasks_list.py
+   :language: python
+
+output::
+
+    Task(task_name=ANALYZE_MOVIE_TASK, attributes=TaskAttributes(instruction='Help the user with their request about movies. User question: {query}. You can use SQL tool to search the data from database', tools='["MOVIE_SQL_TOOL"]', input=None, enable_human_tool=False), description=Movie task involving a human)
+
+.. latex:clearpage::
+
+*********
+``Agent``
+*********
+
+A Select AI Agent is defined using ``agent_name``, its ``attributes`` and an
+optional description. The attributes must include key agent properties such as
+``profile_name`` which specifies the LLM profile used for prompt generation
+and ``role``, which outlines the agent’s intended role and behavioral context.
+
+.. autoclass:: select_ai.agent.AgentAttributes
+   :members:
+
+.. latex:clearpage::
+
+.. autoclass:: select_ai.agent.Agent
+   :members:
+
+.. latex:clearpage::
+
+Create Agent
+++++++++++++
+
+.. literalinclude:: ../../../samples/agent/agent_create.py
+   :language: python
+
+output::
+
+    Created Agent: Agent(agent_name=MOVIE_ANALYST, attributes=AgentAttributes(profile_name='LLAMA_4_MAVERICK', role='You are an AI Movie Analyst. Your can help answer a variety of questions related to movies. ', enable_human_tool=False), description=None)
+
+
+.. latex:clearpage::
+
+****
+Team
+****
+
+AI Agent Team coordinates the execution of multiple agents working together to
+fulfill a user request. Each team is uniquely identified by a ``team_name`` and
+configured through a set of ``attributes`` that define its composition and
+execution strategy. The ``agents`` attribute specifies an array of agent-task
+pairings, allowing users to assign specific tasks to designated agents. User
+can perform multiple tasks by assigning the same agent to different tasks.
+The ``process`` attribute defines how tasks should be executed.
+
+.. autoclass:: select_ai.agent.TeamAttributes
+   :members:
+
+.. latex:clearpage::
+
+.. autoclass:: select_ai.agent.Team
+   :members:
+
+.. latex:clearpage::
+
+Run Team
+++++++++
+
+.. literalinclude:: ../../../samples/agent/team_create.py
+   :language: python
+
+output::
+
+    To list the movies, you can use the SQL query: SELECT m.* FROM "SPARK_DB_USER"."MOVIE" m.

doc/source/user_guide/vector_index.rst

@@ -229,6 +229,7 @@ output::
 
     OracleVectorIndexAttributes(chunk_size=1024, chunk_overlap=128, location='https://objectstorage.us-ashburn-1.oraclecloud.com/n/dwcsdev/b/conda-environment/o/tenant1-pdb3/graph', match_limit=5, object_storage_credential_name='my_oci_ai_profile_key', profile_name='oci_vector_ai_profile', refresh_rate=1450, similarity_threshold=0.5, vector_distance_metric='COSINE', vector_db_endpoint=None, vector_db_credential_name=None, vector_db_provider=<VectorDBProvider.ORACLE: 'oracle'>, vector_dimension=None, vector_table_name=None, pipeline_name='TEST_VECTOR_INDEX$VECPIPELINE')
 
+.. latex:clearpage::
 
 Async RAG using vector index
 ++++++++++++++++++++++++++++

samples/agent/agent_create.py

@@ -0,0 +1,27 @@
+import os
+
+import select_ai
+from select_ai.agent import (
+    Agent,
+    AgentAttributes,
+)
+
+user = os.getenv("SELECT_AI_USER")
+password = os.getenv("SELECT_AI_PASSWORD")
+dsn = os.getenv("SELECT_AI_DB_CONNECT_STRING")
+
+select_ai.connect(user=user, password=password, dsn=dsn)
+
+# Agent
+agent_attributes = AgentAttributes(
+    profile_name="LLAMA_4_MAVERICK",
+    role="You are an AI Movie Analyst. "
+    "Your can help answer a variety of questions related to movies. ",
+    enable_human_tool=False,
+)
+agent = Agent(
+    agent_name="MOVIE_ANALYST",
+    attributes=agent_attributes,
+)
+agent.create(enabled=True, replace=True)
+print("Created Agent:", agent)

samples/agent/movie_analyst.py

@@ -0,0 +1,63 @@
+import os
+import uuid
+
+import select_ai
+from select_ai.agent import (
+    Agent,
+    AgentAttributes,
+    Task,
+    TaskAttributes,
+    Team,
+    TeamAttributes,
+)
+
+user = os.getenv("SELECT_AI_USER")
+password = os.getenv("SELECT_AI_PASSWORD")
+dsn = os.getenv("SELECT_AI_DB_CONNECT_STRING")
+
+select_ai.connect(user=user, password=password, dsn=dsn)
+
+# Agent
+agent_attributes = AgentAttributes(
+    profile_name="oci_ai_profile",
+    role="You are an AI Movie Analyst. "
+    "Your can help answer a variety of questions related to movies. ",
+    enable_human_tool=False,
+)
+agent = Agent(
+    agent_name="MOVIE_ANALYST",
+    attributes=agent_attributes,
+)
+agent.create(enabled=True, replace=True)
+print("Create Agent", agent)
+
+# Task
+task_attributes = TaskAttributes(
+    instruction="Help the user with their request about movies. "
+    "User question: {query}",
+    enable_human_tool=False,
+)
+task = Task(
+    task_name="ANALYZE_MOVIE_TASK",
+    description="Movie task involving a human",
+    attributes=task_attributes,
+)
+task.create(replace=True)
+print("Created Task", task)
+
+# Team
+team_attributes = TeamAttributes(
+    agents=[{"name": "MOVIE_ANALYST", "task": "ANALYZE_MOVIE_TASK"}],
+    process="sequential",
+)
+team = Team(
+    team_name="MOVIE_AGENT_TEAM",
+    attributes=team_attributes,
+)
+team.create(enabled=True, replace=True)
+print(
+    team.run(
+        prompt="In the movie Titanic, was there enough space for Jack ? ",
+        params={"conversation_id": str(uuid.uuid4())},
+    )
+)