chore: import upstream snapshot with attribution

python/samples/02-agents/harness/harness_research.py

@@ -0,0 +1,135 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = [
+#     "agent-framework-foundry",
+#     "textual>=6.2.1",
+#     "rich>=13.7.1",
+#     "azure-identity",
+#     "python-dotenv",
+# ]
+# ///
+# Run with any PEP 723 compatible runner, e.g.:
+#   uv run samples/02-agents/harness/harness_research.py
+
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Harness Research Assistant with Console UI.
+
+Demonstrates ``create_harness_agent`` — a factory function that builds a
+pre-configured agent with batteries included, automatically wiring up function
+invocation, per-service-call history persistence, compaction, and a rich set of
+context providers:
+
+- **TodoProvider** — the agent can create, track, and complete work items
+- **AgentModeProvider** — plan/execute mode tracking (interactive vs. autonomous)
+- **SkillsProvider** — file-based skill discovery and progressive loading
+- **CompactionProvider** — automatic context-window management
+- **InMemoryHistoryProvider** — session history with per-service-call persistence
+- **OpenTelemetry** — built-in observability via AgentTelemetryLayer
+- **Web Search** — real-time web search via ``get_web_search_tool()``
+
+The sample creates a research-focused agent with web search capability and runs
+it inside the Textual-based harness console. The agent will plan research tasks
+using todos, switch between plan and execute modes, search the web for current
+information, and track its progress.
+
+It also demonstrates harness **looping**: a ``loop_should_continue`` predicate
+keeps re-invoking the agent automatically while it is in ``"execute"`` mode and
+the ``TodoProvider`` still has open items, so the agent works through the whole
+plan autonomously once execution begins. A ``loop_next_message`` callable injects
+a reminder between iterations listing the todos that are still open, and the loop
+is scoped to ``"execute"`` mode so ``"plan"`` mode stays interactive.
+``loop_max_iterations`` caps the number of autonomous passes per turn as a safety
+net.
+
+Environment variables:
+    FOUNDRY_PROJECT_ENDPOINT — Azure AI Foundry project endpoint URL
+    FOUNDRY_MODEL            — Model deployment name
+
+Authentication:
+    Run ``az login`` before running this sample.
+"""
+
+import asyncio
+
+from agent_framework import (
+    create_harness_agent,
+    todos_remaining,
+    todos_remaining_message,
+)
+from agent_framework.foundry import FoundryChatClient
+from azure.identity import AzureCliCredential
+from console import build_observers_with_planning, run_agent_async
+from dotenv import load_dotenv
+
+RESEARCH_INSTRUCTIONS = """\
+## Research Assistant Instructions
+
+You are a research assistant. When given a research topic, research it
+thoroughly using web search and web browsing. Use your knowledge to form good
+search queries and hypotheses, but always verify claims with the tools
+available to you rather than relying on memory alone.
+
+### Research quality
+
+Consult multiple sources when possible and cross-reference key claims.
+When sources disagree, note the discrepancy and explain which source you
+consider more reliable and why.
+If a web page fails to load or a search returns irrelevant results, try
+alternative search queries or sources before moving on.
+Track your sources — you will need them when presenting results.
+
+### Presenting results
+
+When presenting your final findings:
+- Use Markdown formatting for clarity.
+- Use clear sections with headings for each major topic or sub-question.
+- Cite your sources inline (e.g., "According to [source name](URL), ...").
+- End with a brief summary of key takeaways.
+- In addition to returning the results to the user, save the final research
+  report to file memory so it survives compaction and can be referenced later.
+"""
+
+
+async def main() -> None:
+    load_dotenv()
+
+    # Create the chat client.
+    # For authentication, run `az login` in terminal or replace AzureCliCredential
+    # with your preferred authentication option.
+    client = FoundryChatClient(credential=AzureCliCredential())
+
+    # Create a harness agent with research-specific instructions.
+    # All other features (todo, mode, compaction, skills, telemetry, web search) are
+    # automatically configured with sensible defaults.
+    agent = create_harness_agent(
+        client=client,
+        max_context_window_tokens=128_000,
+        max_output_tokens=16_384,
+        name="ResearchAgent",
+        description="A research assistant that plans and executes research tasks.",
+        agent_instructions=RESEARCH_INSTRUCTIONS,
+        # Enable harness looping: while the agent is in "execute" mode and still has open todos,
+        # keep re-invoking it automatically so it works through the whole plan without manual
+        # prompting. loop_next_message reminds the agent which todos are still open each pass, and
+        # loop_max_iterations caps the autonomous passes per turn as a safety net.
+        loop_should_continue=todos_remaining(looping_modes=["execute"]),
+        loop_next_message=todos_remaining_message,
+        loop_max_iterations=10,
+    )
+
+    # Run the harness console with the research agent.
+    await run_agent_async(
+        agent,
+        session=agent.create_session(),
+        observers=build_observers_with_planning(agent),
+        initial_mode="plan",
+        title="🔬 Research Assistant",
+        placeholder="Enter a research topic...",
+        max_context_window_tokens=128_000,
+        max_output_tokens=16_384,
+    )
+
+
+if __name__ == "__main__":
+    asyncio.run(main())