Merge pull request #190 from UiPath/samples/agent-framework-orchestrations

Add structured-output, magentic, and sequential samples

Author: cristipufu

packages/uipath-agent-framework/samples/magentic/README.md

@@ -0,0 +1,41 @@
+# Magentic
+
+A multi-agent orchestration based on the Magentic-One pattern. A dedicated manager dynamically coordinates specialized agents (researcher and analyst), selecting who acts next based on task progress and context.
+
+## Agent Graph
+
+```mermaid
+flowchart TB
+  __start__(__start__)
+  magentic_workflow(magentic_workflow)
+  __end__(__end__)
+  __start__ --> |input|magentic_workflow
+  magentic_workflow --> |output|__end__
+```
+
+Internally, the magentic orchestration manages:
+- **researcher** — finds facts via Wikipedia
+- **analyst** — analyzes data and draws conclusions
+- **magentic_manager** — plans, selects the next agent, and tracks progress
+
+The manager dynamically selects which agent should act next based on the evolving context.
+
+## Prerequisites
+
+Authenticate with UiPath to configure your `.env` file:
+
+```bash
+uipath auth
+```
+
+## Run
+
+```
+uipath run agent '{"messages": [{"contentParts": [{"data": {"inline": "Compare the environmental impacts of solar and wind energy production"}}], "role": "user"}]}'
+```
+
+## Debug
+
+```
+uipath dev web
+```

packages/uipath-agent-framework/samples/magentic/main.py

@@ -0,0 +1,72 @@
+import httpx
+from agent_framework.orchestrations import MagenticBuilder
+
+from uipath_agent_framework.chat import UiPathOpenAIChatClient
+
+
+def search_wikipedia(query: str) -> str:
+    """Search Wikipedia for a topic and return a summary.
+
+    Args:
+        query: The search query, e.g. "Python programming language"
+
+    Returns:
+        A summary of the Wikipedia article, or an error message.
+    """
+    try:
+        resp = httpx.get(
+            "https://en.wikipedia.org/api/rest_v1/page/summary/"
+            + query.replace(" ", "_"),
+            headers={"User-Agent": "UiPathMagentic/1.0"},
+            timeout=10,
+            follow_redirects=True,
+        )
+        resp.raise_for_status()
+        data = resp.json()
+        return data.get("extract", "No summary available.")
+    except Exception as e:
+        return f"Wikipedia search failed for '{query}': {e}"
+
+
+client = UiPathOpenAIChatClient(model="gpt-5-mini-2025-08-07")
+
+researcher = client.as_agent(
+    name="researcher",
+    description="Specialist in research and information gathering using Wikipedia.",
+    instructions=(
+        "You are a Researcher. Use the search_wikipedia tool to find factual "
+        "information. Provide concise, well-sourced responses without additional "
+        "computation or quantitative analysis."
+    ),
+    tools=[search_wikipedia],
+)
+
+analyst = client.as_agent(
+    name="analyst",
+    description="Specialist in analyzing data and drawing conclusions.",
+    instructions=(
+        "You are an Analyst. Analyze the information gathered by other agents. "
+        "Draw conclusions, identify patterns, and provide actionable insights. "
+        "Be precise and support your analysis with evidence from the discussion."
+    ),
+)
+
+manager = client.as_agent(
+    name="magentic_manager",
+    description="Orchestrator that coordinates the research and analysis workflow.",
+    instructions=(
+        "You coordinate a team of researcher and analyst to complete complex "
+        "tasks efficiently. Break down problems, delegate subtasks, and "
+        "synthesize results into a comprehensive final answer."
+    ),
+)
+
+workflow = MagenticBuilder(
+    participants=[researcher, analyst],
+    manager_agent=manager,
+    max_round_count=6,
+    max_stall_count=2,
+    max_reset_count=1,
+).build()
+
+agent = workflow.as_agent(name="magentic_workflow")

packages/uipath-agent-framework/samples/magentic/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "magentic"
+version = "0.0.1"
+description = "Magentic: dynamic multi-agent orchestration with a planning manager"
+authors = [{ name = "John Doe" }]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "uipath",
+    "uipath-agent-framework",
+    "agent-framework-core>=1.0.0rc1",
+    "agent-framework-orchestrations>=1.0.0b260219",
+]
+
+[dependency-groups]
+dev = [
+    "uipath-dev",
+]
+
+[tool.uv]
+prerelease = "allow"

packages/uipath-agent-framework/samples/sequential/README.md

@@ -0,0 +1,41 @@
+# Sequential
+
+A sequential pipeline where agents process a task one after another. A writer creates marketing copy, a reviewer provides feedback, and an editor produces the polished final version.
+
+## Agent Graph
+
+```mermaid
+flowchart TB
+  __start__(__start__)
+  sequential_workflow(sequential_workflow)
+  __end__(__end__)
+  __start__ --> |input|sequential_workflow
+  sequential_workflow --> |output|__end__
+```
+
+Internally, the sequential orchestration chains:
+- **writer** — creates an initial marketing paragraph
+- **reviewer** — provides constructive feedback on the draft
+- **editor** — incorporates feedback and produces the final polished version
+
+Each agent sees the full conversation history from previous agents.
+
+## Prerequisites
+
+Authenticate with UiPath to configure your `.env` file:
+
+```bash
+uipath auth
+```
+
+## Run
+
+```
+uipath run agent '{"messages": [{"contentParts": [{"data": {"inline": "Write a tagline for a budget-friendly eBike"}}], "role": "user"}]}'
+```
+
+## Debug
+
+```
+uipath dev web
+```

packages/uipath-agent-framework/samples/sequential/main.py

@@ -0,0 +1,40 @@
+from agent_framework.orchestrations import SequentialBuilder
+
+from uipath_agent_framework.chat import UiPathOpenAIChatClient
+
+client = UiPathOpenAIChatClient(model="gpt-5-mini-2025-08-07")
+
+writer = client.as_agent(
+    name="writer",
+    description="Creates concise, engaging marketing copy.",
+    instructions=(
+        "You are a concise copywriter. Provide a single, punchy marketing "
+        "paragraph based on the prompt. Focus on clarity and impact."
+    ),
+)
+
+reviewer = client.as_agent(
+    name="reviewer",
+    description="Reviews and provides constructive feedback on content.",
+    instructions=(
+        "You are a thoughtful reviewer. Give brief, constructive feedback "
+        "on the previous assistant message. Highlight strengths and suggest "
+        "one specific improvement."
+    ),
+)
+
+editor = client.as_agent(
+    name="editor",
+    description="Polishes content based on feedback into a final version.",
+    instructions=(
+        "You are a skilled editor. Based on the original content and the "
+        "reviewer's feedback, produce a polished final version. Incorporate "
+        "the suggested improvements while maintaining the original tone."
+    ),
+)
+
+workflow = SequentialBuilder(
+    participants=[writer, reviewer, editor],
+).build()
+
+agent = workflow.as_agent(name="sequential_workflow")

packages/uipath-agent-framework/samples/sequential/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "sequential"
+version = "0.0.1"
+description = "Sequential: agents process a task in a pipeline, each building on the previous output"
+authors = [{ name = "John Doe" }]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "uipath",
+    "uipath-agent-framework",
+    "agent-framework-core>=1.0.0rc1",
+    "agent-framework-orchestrations>=1.0.0b260219",
+]
+
+[dependency-groups]
+dev = [
+    "uipath-dev",
+]
+
+[tool.uv]
+prerelease = "allow"

packages/uipath-agent-framework/samples/structured-output/README.md

@@ -0,0 +1,34 @@
+# Structured Output
+
+A simple workflow agent that returns structured data using a Pydantic model. The agent extracts city information (name, country, description, population, and notable features) and returns it in a well-defined JSON schema.
+
+## Agent Graph
+
+```mermaid
+flowchart TB
+  __start__(__start__)
+  city_agent(city_agent)
+  __end__(__end__)
+  __start__ --> |input|city_agent
+  city_agent --> |output|__end__
+```
+
+## Prerequisites
+
+Authenticate with UiPath to configure your `.env` file:
+
+```bash
+uipath auth
+```
+
+## Run
+
+```
+uipath run agent '{"messages": [{"contentParts": [{"data": {"inline": "Tell me about Tokyo"}}], "role": "user"}]}'
+```
+
+## Debug
+
+```
+uipath dev web
+```

packages/uipath-agent-framework/samples/structured-output/main.py

@@ -0,0 +1,29 @@
+from agent_framework import WorkflowBuilder
+from pydantic import BaseModel
+
+from uipath_agent_framework.chat import UiPathOpenAIChatClient
+
+
+class CityInfo(BaseModel):
+    """Structured output for city information."""
+
+    city: str
+    country: str
+    description: str
+    population_estimate: str
+    famous_for: list[str]
+
+
+client = UiPathOpenAIChatClient(model="gpt-5-mini-2025-08-07")
+city_agent = client.as_agent(
+    name="city_agent",
+    instructions=(
+        "You are a helpful agent that describes cities in a structured format. "
+        "Given a city name, provide the city name, country, a brief description, "
+        "an estimated population, and a list of things the city is famous for."
+    ),
+    response_format=CityInfo,
+)
+
+workflow = WorkflowBuilder(start_executor=city_agent).build()
+agent = workflow.as_agent(name="structured_output_workflow")

packages/uipath-agent-framework/samples/structured-output/pyproject.toml

@@ -0,0 +1,20 @@
+[project]
+name = "structured-output"
+version = "0.0.1"
+description = "Structured output: agent returns data in a well-defined Pydantic schema"
+authors = [{ name = "John Doe" }]
+readme = "README.md"
+requires-python = ">=3.11"
+dependencies = [
+    "uipath",
+    "uipath-agent-framework",
+    "agent-framework-core>=1.0.0rc1",
+]
+
+[dependency-groups]
+dev = [
+    "uipath-dev",
+]
+
+[tool.uv]
+prerelease = "allow"