Supervisor Agent Pattern
Create a supervisor-led Select AI agent team that routes multi-step requests to specialized worker agents and returns one coordinated response.
A Select AI supervisor agent is the Select AI agent object that controls a supervisor-led agent team at runtime. The supervisor agent object receives the user prompt, selects the worker agent-task pair that should handle each subtask, passes the required context, waits for that worker result, and continues to select the next agent-task pair until it can return a final answer.
The following image illustrates Select AI supervisor agent pattern.
Description of the illustration select-ai-supervisor-agentic-pattern.png
When to Use a Supervisor Agent
Use the supervisor pattern when the team must determine the appropriate workers or run order at run time. A supervisor-led team can help when a request requires different workers, in different orders, depending on the user’s intent and the intermediate results. The supervisor decides which worker agent-task pair to call next, passes a self-contained subtask, waits for the result, and continues until it can produce one coordinated final answer.
A supervisor agent is suitable for:
- Workflows that span distinct business or technical domains.
- Requests that require different agents, tools, or data sources.
- Agent teams that require a single entry point for routing and coordinating requests.
- Workflows in which the supervisor must manage the interaction sequence and consolidate subagent responses.
About Select AI Supervisor Agent Teams
Understand how a Select AI supervisor agent team coordinates worker agents, controls task routing, preserves context, and returns one final response.
A supervisor agent team is an orchestration pattern for a Select AI agent team. In that team, one Select AI agent object is identified as the supervisor by setting its supervisor attribute to true, and the team names that object in the supervisor_agent attribute. Worker agents keep focused responsibilities, such as account lookup, payment retrieval, report generation, or notification delivery. The supervisor agent object decides which worker to call, prepares a self-contained request for that worker, and adds the worker result back into the supervisor context.
Subtask processing is sequential: one worker subtask must finish before the supervisor delegates the next subtask. The supervisor waits for the worker result, adds the result to the supervisor context, and then decides whether to call another worker, request more information, explain a worker failure, or return the final answer. Worker agents use separate conversation threads, so the supervisor must include enough context in each delegated request.
The feature adds supervisor-related attributes to existing DBMS_CLOUD_AI_AGENT APIs. Use the supervisor agent attribute to mark a Select AI agent object as the supervisor. Use the supervisor_agent team attribute to name that supervisor agent object for a team. A supervised team contains one supervisor agent object and one or more worker agent-task pairs. The agents team attribute lists the worker agent-task pairs available for delegation. Each worker task can use its configured tools. The supervisor agent object delegates to worker agent-task pairs; the Oracle-maintained delegation tool is not user-configurable.
See Example: Build and Run a Customer Support Supervisor Team for an end-to-end example of using a supervisor agent.
Select AI Supervisor Agent Architecture
A supervised Select AI agent team runs as a single team with one supervisor agent object and one or more worker agent-task pairs. The team definition names the supervisor agent object in supervisor_agent; the worker list names the agent-task pairs to which the supervisor can delegate. Tools are configured on worker tasks, not on the team.
In a supervisor-led team, process is still set to sequential, but the configured worker order is not the workflow plan. The supervisor dynamically selects one worker agent-task pair at a time, waits for the result, and then decides whether another worker is needed.
The supervisor agent object uses an Oracle-maintained delegation tool internally to delegate to a worker agent-task pair. The delegation tool is part of the supervisor execution model and is not listed as a user-configurable team attribute.
The supervisor owns the overall request and runs in its own conversation thread. Each worker agent runs in a separate conversation thread. A worker does not inherit the full supervisor context. The supervisor must create a self-contained subtask request for each worker. The worker returns only its final result to the supervisor. The supervisor adds the returned result to its own context and decides the next action.
Description of the illustration select-ai-supervisor-agent-workflow.png
| Phase | Input | Processing | Output |
|---|---|---|---|
| Request submission | User natural-language request submitted to the team | The supervised team activates the supervisor agent first. | Supervisor conversation thread starts for the request. |
| Supervisor reasoning loop | User request and current supervisor context | The supervisor decides whether it has enough information to answer or must delegate a subtask. | Final answer or one delegated worker request. |
| Task delegation | Selected worker agent-task pair and self-contained subtask context | The supervisor calls the Oracle-maintained delegation tool for the selected worker agent-task pair and waits. | Worker task starts in its own conversation thread. |
| Task processing | Delegated subtask and worker task configuration | The worker uses the tools configured on its task. If it needs user input, then the team waits for the user response. | Worker result, worker failure result, or a human-input request. |
| Supervisor continuation | Returned worker result, failure result, or user response | The supervisor adds the returned result to its context and continues reasoning. Failure follows the same return path as success; the supervisor decides whether to retry, call another worker, request more information, explain the failure, or return the final answer. |
Runtime Behavior in Supervisor-Led Teams
Learn how supervisor-led teams pause for user input, handle worker failures, and pass self-contained context between supervisor and worker conversations.
Human Input Handling
When a worker requests human input, the entire supervisor-led team pauses while waiting for the user response. The user continues in the same conversation to provide the requested information.
After the user responds, the worker resumes, completes the task, and returns the result to the supervisor. The supervisor then decides whether to delegate another subtask or return the final answer.
Failure Handling
Worker failures follow the same return path as successful results. The supervisor receives the failure result and decides the next action, such as retrying the task, calling another worker agent-task pair, requesting additional input, or returning a final answer.
Context Passing Model
Each worker operates in its own conversation thread and does not inherit the full supervisor context. The supervisor must provide a self-contained subtask request that includes all required information for the worker to complete the task.
Use Cases for Supervisor Agent
Apply supervisor-led Select AI teams when one request may require several specialized agents, conditional routing, or a staged response.
- Answer a customer-support request that needs account details, payment history, and a final combined response.
- Route a data analysis prompt to the right worker based on the data source, then combine worker results in one answer.
- Ask a worker to pause for human confirmation before sending a notification or completing a business action.
- Use one supervisor team for requests that sometimes require one worker and sometimes require several workers in sequence.
- Track worker handoffs and returned results for audit, testing, and troubleshooting.
Benefits
Use supervisor-led teams to route multi-step requests, keep worker agents focused, and record delegation paths for Select AI agent framework activity.
- Dynamic task routing: The supervisor selects the next worker based on the current request and returned context.
- Focused worker design: Each worker handles a bounded task area, which keeps prompts and tool mappings easier to maintain.
- Context control: The supervisor passes only the context needed for each worker subtask.
- Traceability: Team and task history views can show the delegation path and returned worker results.
- Incremental team growth: Add new worker agents for new tasks without redesigning every existing worker.