Planning design for agents

Who this is for and what you will get

This is for developers who want an agent to handle a multi-step task without hand-writing the whole flow each time. After reading, you should be able to split a vague goal into subtasks, have the model return a structured plan as JSON, and route each subtask to the right agent.^[1]

What planning solves

Most real tasks cannot be finished in one step. An agent needs a concise objective to guide its planning and actions. The example goal is "Generate a 3-day travel itinerary." It sounds simple, but it still needs refinement. The clearer the goal, the more easily the agent and any people involved can aim at the right result, such as a complete itinerary with flight options, hotel recommendations, and activity suggestions.^[1]

Step 1: split the goal into subtasks

The itinerary can be split into four subtasks: flight booking, hotel booking, car rental, and personalization. Each subtask can be handled by a dedicated agent. A coordinating agent, sometimes called a downstream agent, then compiles the results into one cohesive itinerary.^[1]

The modular structure also makes later expansion easy. You could add agents for food recommendations or local activity suggestions and refine the itinerary over time.^[1]

Step 2: have the model return a structured plan

Large language models can produce structured output such as JSON, which downstream agents or services can parse and process more easily. This matters most in multi-agent systems, where the plan is the input for executing each subtask.^[1]

The sample uses Pydantic to define its data structures. First, the imports:^[1]

from pydantic import BaseModel
from enum import Enum
from typing import List, Optional, Union
import json
import os
from typing import Optional
from pprint import pprint
from agent_framework.foundry import FoundryChatClient
from azure.identity import AzureCliCredential

The agent types are a string enum called AgentEnum with seven members, from flight_booking to group_chat_manager. The plan is modeled with two classes. TravelSubTask has task_details and assigned_agent, and TravelPlan has main_task, subtasks, and is_greeting.^[1]

class AgentEnum(str, Enum):
    FlightBooking = "flight_booking"
    HotelBooking = "hotel_booking"
    CarRental = "car_rental"
    ActivitiesBooking = "activities_booking"
    DestinationInfo = "destination_info"
    DefaultAgent = "default_agent"
    GroupChatManager = "group_chat_manager"

# Travel SubTask Model
class TravelSubTask(BaseModel):
    task_details: str
    assigned_agent: AgentEnum  # we want to assign the task to the agent

class TravelPlan(BaseModel):
    main_task: str
    subtasks: List[TravelSubTask]
    is_greeting: bool

The client is created with FoundryChatClient. It reads the project endpoint and model deployment name from the environment variables AZURE_AI_PROJECT_ENDPOINT and AZURE_AI_MODEL_DEPLOYMENT_NAME, and it authenticates with AzureCliCredential.^[1]

provider = FoundryChatClient(
    project_endpoint=os.environ["AZURE_AI_PROJECT_ENDPOINT"],
    model=os.environ["AZURE_AI_MODEL_DEPLOYMENT_NAME"],
    credential=AzureCliCredential(),
)

The system prompt tells the model that it is a planner agent that decides which agents to run based on the user's request. It asks for JSON with main_task and subtasks, where each subtask has assigned_agent and task_details. Six agents are listed: flight booking, hotel booking, car rental, activities booking, destination information, and a default agent.^[1]

The sample's user message is "Create a travel plan for a family of 2 kids from Singapore to Melbourne." The response text is parsed with json.loads and printed with pprint.^[1]

Step 3: route each subtask by assigned_agent

With the structured output in hand, use each subtask's assigned_agent field to route it to the matching agent, then summarize the plan for the user.^[1]

The planner handles two cases. If there is only one subtask, it sends the message straight to a dedicated agent. If there are several, it coordinates the agents through a group chat manager. An agent registry records which agents exist and which functions or tools each one offers.^[1]

Pitfalls in the sample code

Both samples assign the client to provider, but the call that follows is written as client.create_response. If you copy the code as it is, client will not be defined. Use one name throughout.^[1]
In the sample output, is_greeting is the string "False", not a boolean. If your code branches on it, convert it or check for the string.^[1]
The system prompt lists six agents, but the enum has seven values. group_chat_manager is in the enum and not in the prompt's list.^[1]
The iterative planning code is marked e.g sample code, and its first line is a comment that says it is the same as the previous code. It depends on earlier code and will not run on its own.^[1]

When the plan has to change

Some tasks need back-and-forth, because the result of one subtask changes the next. For example, an agent that finds an unexpected data format while booking flights may need to change its approach before it books hotels. User feedback can also trigger a partial re-plan, such as a traveler who prefers an earlier flight. The point is to keep the final plan within real constraints and the user's changing preferences.^[1]

A more complete option: Magentic-One

For more thorough planning, look at Microsoft Research's Magentic-One. It is described as a generalist multi-agent system for complex tasks that has achieved strong results on several challenging agent benchmarks. Its orchestrator creates task-specific plans, delegates the tasks to available agents, tracks progress, and re-plans when needed.^[1]

Limits and common questions

The planner assumes that each agent already has the functions or tools it needs. Confirm this for every agent you build, because the planner does not supply tools.^[1]
The sample stops at planning, routing, and summarizing. Patterns such as reflection, a summarizer, or round-robin group chat can be layered on top to customize the system further.^[1]
Structured output depends on the model returning the requested format. Spell out field names and enum values in the prompt, and validate the parsed result.