Agent Tool Guidelines in Generative AI Agents

Understand the properties and responsibilities of a supervisor agent and its collaborator agents.

• The supervisor agent and a collaborator agent can belong to different tenancies.

• A collaborator agent can be an agent with any tool type (such as RAG tool) or combination of tool types (such as RAG and Function calling tools), as long as the agent is associated with an active agent endpoint.

• The agent that's configured as an Agent tool can operate independently and be integrated in a supervisor agent.

• Additional tools (such as RAG and SQL) can be included in the supervisor agent with collaborator agents.

• The supervisor agent is responsible for:

  • Session management and query routing

  • Aggregating responses from collaborator agents or tools

  • Maintaining a global chat history

• A collaborator agent is responsible for:

  • Handling queries relevant to its specialization (for example, HR)
  • Maintaining a localized chat history tied to the global session.

• Metrics and billing is handled separately for the supervisor agent, collaborator agents, and tools.

A possible data flow scenario involving responses from multiple collaborator agents might be described as follows:

1. A user sends a query to the supervisor agent in a chat session. The query spans more than one specialization.
2. The supervisor agent splits the query and delegates the subqueries to the relevant collaborator agents based on routing logic.
3. Each collaborator agent processes its subquery using its session context. The collaborator agents return their responses to the supervisor agent.
4. The supervisor agent aggregates and formats the responses into a consolidated output, and sends the output to the user.

The workflow for implementing collaborator agents and a supervisor agent is:

1. Understand and add the OCI Identity and Access Management (IAM) policies that are required. See IAM Policies.
2. Create the collaborator agents using any tool. If you need help, see Creating an Agent.
3. Ensure that each collaborator agent has an associated agent endpoint that's active and enabled for session. If you need help, see Getting an Endpoint's Details.
4. Create the supervisor agent. Use the Agent tool type to add the collaborator agents. If you need help, see Creating an Agent Tool.
5. Ensure that the agent endpoint for the supervisor agent is enabled for session. If you need help, see Getting an Endpoint's Details.

Ensure that you give users access to all Generative AI Agents resources as described in Adding Policies Before You Can Use the Service.

Review also the following sections.

Dynamic Group and Policy

You need to add a dynamic group with permission to manage genai-agent-family.

1. Create a dynamic group, and add the following matching rule.

   ALL {resource.type='genaiagent'}

   If you need help, see Creating a Dynamic Group.

2. Give permission to the dynamic group.

   • Write the following policy, which can be used with the Default identity domain:

     allow dynamic-group <dynamic-group-name> 
     to manage genai-agent-family in tenancy
     

   • Use the following policy with an identity domain that's not Default, providing the Oracle Identity Cloud Service (IDCS) domain name and the dynamic group name:

     allow dynamic-group '<idcs-domain-name>/<dynamic-group-name>' 
     to manage genai-agent-family in tenancy
     

   See About Generative AI Agents Resource-Types to assign permissions based on individual resource types instead of the aggregate resource type.

Cross-Tenancy Access

To use an agent endpoint that's from another tenancy, certain policies must be set up in the target tenancy and in the tenancy where you're creating the Agent tool. Gather the following information:

• The target tenancy name and OCID. Target tenancy is the tenancy that has the active agent endpoint that you want to use.
• The tenancy name and OCID where you're creating an Agent tool.
• The dynamic group name and OCID.

Write the following cross-tenancy policy statements. If applicable, use the form '<idcs-domain-name>/<dynamic-group-name>' in the syntax for usage in an identity domain that's not Default.

In the tenancy where you're creating an Agent tool:

<target-tenancy> is the tenancy that has the active agent endpoint that you want to use.

Define tenancy <target-tenancy> as <target-tenancy-ocid>

Endorse dynamic-group <dynamic-group-name> to manage genai-agent-family in tenancy <target-tenancy>

In the target tenancy:

<this-tenancy> is the tenancy where you're creating an Agent tool.

Define tenancy <this-tenancy> as <this-tenancy-ocid>

Define dynamic-group <dynamic-group-name> as <dynamic-group-ocid>

Admit dynamic-group <dynamic-group-name> of tenancy <this-tenancy> to manage genai-agent-family in tenancy

If you need help, see Cross-Tenancy Access Policies in the documentation for OCI IAM with Identity Domains.

An Agent tool supports only an agent with an agent endpoint that has session enabled.

When session is enabled on an agent endpoint to keep the context of a chat session, Generative AI Agents creates a session ID and persists the agent session for the interactive conversation. During the session, context and continuity are maintained to provide coherent and meaningful responses throughout the conversation.

For a collaborator agent that's to be configured in a supervisor agent, ensure that the agent has only a session-based agent endpoint. The supervisor agent must also only be associated with an agent endpoint that has session enabled.

By default, when you use the Console to create an agent and choose to automatically create the agent endpoint at the same time, session is enabled on the agent endpoint that's created with the agent. To verify, you can view the details of the endpoint in the agent.

If you create an agent endpoint manually, ensure that Enable session is selected if the endpoint is to be configured with an Agent tool.

Before you create an Agent tool, gather the following information:

• The name of the agent to be added as a tool.
• The name of the active, session-based agent endpoint for that agent. Create an agent endpoint if the agent doesn't have an active endpoint that you can use. If you need help, see Creating an Endpoint.
• If the agent endpoint is in a different tenancy from the tenancy where you're creating the Agent tool, get the agent endpoint OCID. If you need help, see Getting an Endpoint's Details.