Orchestrator (Autonomous)

The orchestrator pattern uses a central AI agent that autonomously decides which specialized agents to delegate to and in what order.

When to use this

Choose the orchestrator when the correct order of agents depends on the input, and the AI must plan this order. If the steps are always the same, a deterministic workflow is simpler and cheaper.

UC AI gives each delegate agent to the orchestrator as a tool. The AI decides the flow from the task.

If you need the same specialist in more than one caller, or together with normal tools, register it as a permanent tool. Read the agent as tool guide.

How it works

1. UC AI registers each delegate agent as a temporary tool for the orchestrator
2. The prompt profile of the orchestrator holds the instructions for the coordination of the delegates
3. The orchestrator AI decides which agents to call, in what order, and with what parameters
4. Each delegation runs the referenced agent and returns its result
5. The orchestrator synthesizes the results into a final answer
6. UC AI deletes the temporary tools after the run

Example: travel planner

This example shows an orchestrator that coordinates calendar, flight, and hotel agents to plan a business trip.

Step 1: Create prompt profiles

Each agent needs a prompt profile with instructions, provider, and model configuration.

In a real system, each agent reads an external data source or an API. This example holds the data in the system prompt, to stay simple.

DECLARE
  l_profile_id NUMBER;
BEGIN
  -- Calendar agent: knows the user's schedule
  l_profile_id := uc_ai_prompt_profiles_api.create_prompt_profile(
    p_code                  => 'calendar_agent_profile',
    p_description           => 'Provides calendar and scheduling information',
    p_system_prompt_template => 'You have access to the users calendar.
Schedule:
- Monday 12.01: 8-11 AM Board Meeting (New York, non-reschedulable), 1-2 PM team lunch
- Tuesday 13.01: 9 AM-12 PM Tech Conference (San Francisco, mandatory)
- Wednesday 14.01: Free all day
- Thursday 15.01: Free until 3 PM, 3-5 PM client call (remote, mandatory)
Note: User is in New York, needs ~6 hours for cross-country travel to SF.
Answer shortly and precisely.',
    p_user_prompt_template  => 'Calendar query: {prompt}',
    p_provider              => uc_ai.c_provider_openai,
    p_model                 => uc_ai_openai.c_model_gpt_5_6_luna,
    p_status                => uc_ai_prompt_profiles_api.c_status_active
  );

  -- Flight booking agent: knows available flights
  l_profile_id := uc_ai_prompt_profiles_api.create_prompt_profile(
    p_code                  => 'flight_booking_agent_profile',
    p_description           => 'Provides flight booking options',
    p_system_prompt_template => 'You are a flight booking assistant.
Available flights JFK to SFO:
1. AA123: 12 PM-3 PM, $450, Economy, American Airlines
2. UA456: 2 PM-5 PM, $385, Economy, aisle, United Airlines
3. DL789: 5 PM-8 PM, $520, Business, Delta
4. B6999: 7 PM-10 PM, $340, Economy, Budget Air
Return flights available 2 hours later same day.
Return 3 best options based on preferences. No additional text.',
    p_user_prompt_template  => 'Flight search: {prompt}',
    p_provider              => uc_ai.c_provider_openai,
    p_model                 => uc_ai_openai.c_model_gpt_5_6_luna,
    p_status                => uc_ai_prompt_profiles_api.c_status_active
  );

  -- Hotel booking agent: knows available hotels
  l_profile_id := uc_ai_prompt_profiles_api.create_prompt_profile(
    p_code                  => 'hotel_booking_agent_profile',
    p_description           => 'Provides hotel accommodation options',
    p_system_prompt_template => 'You are a hotel booking assistant.
Available hotels near SF Tech Conference:
1. Grand Hyatt: 0.2 mi, $320/night, 4.5 stars
2. Holiday Inn: 0.8 mi, $180/night, 3.8 stars
3. Marriott Marquis: 0.5 mi, $280/night, 4.3 stars
4. Airport Hotel Express: 15 mi, $120/night, 3.5 stars
Return 3 best options based on preferences. No additional text.',
    p_user_prompt_template  => 'Hotel search: {prompt}',
    p_provider              => uc_ai.c_provider_openai,
    p_model                 => uc_ai_openai.c_model_gpt_5_6_luna,
    p_status                => uc_ai_prompt_profiles_api.c_status_active
  );

  -- Orchestrator: coordinates the other agents
  l_profile_id := uc_ai_prompt_profiles_api.create_prompt_profile(
    p_code                  => 'travel_planner_orchestrator',
    p_description           => 'Orchestrates travel planning',
    p_system_prompt_template => 'You are a travel planning coordinator.
You have access to calendar, flight, and hotel booking agents.
First check the calendar for constraints, then find flights and hotels that fit.
Provide a recommended travel plan with reasoning.',
    p_user_prompt_template  => '{prompt}',
    p_provider              => uc_ai.c_provider_openai,
    p_model                 => uc_ai_openai.c_model_gpt_5_6_luna,
    p_status                => uc_ai_prompt_profiles_api.c_status_active
  );

  COMMIT;
END;
/

Tip

Use a more capable model for the orchestrator, here GPT-5 Mini. It must reason about which agents to call. A delegate agent can use a cheaper model, because its task is narrow.

Step 2: Create delegate agents

Each delegate agent wraps a prompt profile and needs an input_schema so the orchestrator knows what parameters to pass.

DECLARE
  l_agent_id     NUMBER;
  l_input_schema json_object_t;
BEGIN
  l_input_schema := json_object_t('{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "type": "object",
    "properties": {
      "prompt": {
        "type": "string",
        "description": "The query or context for the agent"
      }
    },
    "required": ["prompt"]
  }');

  l_agent_id := uc_ai_agents_api.create_agent(
    p_code                => 'calendar_agent',
    p_description         => 'Provides calendar and scheduling information. Call this to check availability and scheduling constraints.',
    p_agent_type          => uc_ai_agents_api.c_type_profile,
    p_prompt_profile_code => 'calendar_agent_profile',
    p_status              => uc_ai_agents_api.c_status_active,
    p_input_schema        => l_input_schema.to_clob
  );

  l_agent_id := uc_ai_agents_api.create_agent(
    p_code                => 'flight_booking_agent',
    p_description         => 'Provides flight booking options between cities. Call this to search for available flights.',
    p_agent_type          => uc_ai_agents_api.c_type_profile,
    p_prompt_profile_code => 'flight_booking_agent_profile',
    p_status              => uc_ai_agents_api.c_status_active,
    p_input_schema        => l_input_schema.to_clob
  );

  l_agent_id := uc_ai_agents_api.create_agent(
    p_code                => 'hotel_booking_agent',
    p_description         => 'Provides hotel accommodation options near destinations. Call this to search for hotels.',
    p_agent_type          => uc_ai_agents_api.c_type_profile,
    p_prompt_profile_code => 'hotel_booking_agent_profile',
    p_status              => uc_ai_agents_api.c_status_active,
    p_input_schema        => l_input_schema.to_clob
  );

  COMMIT; -- agents must be committed before they can be executed
END;
/

Note

The orchestrator AI sees the p_description of each delegate agent when it decides which agent to call. Write a clear and specific description. The description controls how well the orchestrator delegates.

Step 3: Create the orchestrator

DECLARE
  l_orchestrator_id NUMBER;
  l_orch_config     CLOB;
BEGIN
  l_orch_config := '{
    "pattern_type": "orchestrator",
    "orchestrator_profile_code": "travel_planner_orchestrator",
    "delegate_agents": [
      "calendar_agent",
      "flight_booking_agent",
      "hotel_booking_agent"
    ],
    "max_delegations": 8
  }';

  l_orchestrator_id := uc_ai_agents_api.create_agent(
    p_code                 => 'travel_planner',
    p_description          => 'Plans travel by coordinating calendar, flights, and hotels',
    p_agent_type           => uc_ai_agents_api.c_type_orchestrator,
    p_orchestration_config => l_orch_config,
    p_status               => uc_ai_agents_api.c_status_active
  );

  COMMIT;
END;
/

Step 4: Execute

DECLARE
  l_result json_object_t;
BEGIN
  l_result := uc_ai_agents_api.execute_agent(
    p_agent_code       => 'travel_planner',
    p_input_parameters => json_object_t('{
      "prompt": "I need to travel from New York to San Francisco for a tech conference on Tuesday. I have a board meeting Monday until 11 AM."
    }'),
    p_session_id       => uc_ai_agents_api.generate_session_id
  );

  DBMS_OUTPUT.PUT_LINE('Plan: ' || l_result.get_clob('final_message'));
  DBMS_OUTPUT.PUT_LINE('Agents called: ' || l_result.get_number('tool_calls_count'));
END;
/

The orchestrator AI then does this work itself:

1. Check the calendar for scheduling constraints
2. Search for flights that fit after the Monday meeting
3. Find hotels near the conference venue
4. Synthesize everything into a recommended travel plan

Config reference

Field	Type	Description
pattern_type	String	Must be "orchestrator"
orchestrator_profile_code	String	Prompt profile code for the orchestrator AI
delegate_agents	Array	List of agent codes the orchestrator can call
max_delegations	Number	Maximum number of agent calls allowed

Conversation continuation

An orchestrator supports a follow-up message with p_follow_up_message, the same as a profile agent. You can therefore correct or extend the work of the orchestrator after you read its first plan:

DECLARE
  l_result     json_object_t;
  l_session_id VARCHAR2(100);
BEGIN
  l_session_id := uc_ai_agents_api.generate_session_id;

  -- Initial request
  l_result := uc_ai_agents_api.execute_agent(
    p_agent_code       => 'travel_planner',
    p_input_parameters => json_object_t('{
      "prompt": "Plan a trip from New York to San Francisco for Tuesday."
    }'),
    p_session_id       => l_session_id
  );

  DBMS_OUTPUT.PUT_LINE(l_result.get_clob('final_message'));

  -- Follow-up: orchestrator can call delegates again
  l_result := uc_ai_agents_api.execute_agent(
    p_agent_code        => 'travel_planner',
    p_follow_up_message => 'Actually, I prefer business class. Can you find better flight options?',
    p_session_id        => l_session_id
  );

  DBMS_OUTPUT.PUT_LINE(l_result.get_clob('final_message'));
END;
/

On each follow-up call, UC AI registers the delegate agents again as temporary tools. The orchestrator can therefore delegate more work. UC AI sends the full conversation history to the LLM, with the earlier tool calls and their results.

Message log at a glance

The orchestrator makes the model calls itself, and it reaches each delegate through a tool call. The uc_ai_agent_messages transcript therefore records each delegate as a tool_call and tool_result pair, with the delegate agent in tool_name. These pairs stand around the own reasoning and the final synthesis of the orchestrator. The orchestrator is a direct pattern, so agent_code names it on every agent row. The tool_name of a tool row names the delegate.

SELECT seq, role, agent_code, tool_name, SUBSTR(content, 1, 50) AS content
  FROM uc_ai_agent_messages
 WHERE session_id = :session_id
 ORDER BY seq;

seq	role	agent_code	tool_name	content
1	user	(null)		Plan my NYC -> SF trip ...
2	tool_call	travel_orchestrator	calendar_agent
3	tool_result	travel_orchestrator	calendar_agent	Board meeting ends 11:00 AM...
4	tool_call	travel_orchestrator	flight_booking_agent
5	tool_result	travel_orchestrator	flight_booking_agent	Direct flights: UA 514 ...
6	assistant	travel_orchestrator		Recommended plan: depart ...

Tips

• Give the orchestrator a plan: describe the strategy for the delegates in the system prompt of the orchestrator. An example is “First check calendar constraints, then search flights, then hotels.”
• Limit the delegations: set max_delegations to stop excessive calls. The orchestrator needs room for every relevant agent, but it must not loop forever.
• Use structured output on the orchestrator: if you need the final answer in a fixed format, add a response schema to the prompt profile of the orchestrator.
• Write a precise input schema: the input_schema of a delegate agent defines how the orchestrator calls it. A clear schema with a good description for each field helps the AI pass the correct parameters.