chore: import upstream snapshot with attribution

2026-07-13 13:39:25 +08:00
commit db620d33df
5151 changed files with 925932 additions and 0 deletions
@@ -0,0 +1,90 @@
+# local_responses — Responses helpers with native FastAPI routes
+
+The smallest end-to-end Responses hosting shape: one Foundry agent with a
+`@tool`, one native FastAPI route, a small `SessionStore`, and the Responses
+helper functions:
+
+- `responses_to_run(...)`
+- `responses_session_id(...)`
+- `create_response_id(...)`
+- `responses_from_run(...)`
+
+The sample demonstrates the lighter hosting direction. Agent Framework provides
+the run conversion and session-state pieces; FastAPI owns route registration,
+request bodies, response objects, and server startup.
+
+What the route demonstrates:
+
+- Uses an explicit request-option allowlist. This sample only allows
+  `max_tokens` and then overrides `reasoning`; all other caller-supplied
+  options, including `model`, `temperature`, `store`, `tools`, and
+  `tool_choice`, are denied by default. Your app decides the exact allowed,
+  altered, and denied options.
+- **Forces** a `reasoning` preset (`effort=medium`, `summary=auto`) on every
+  turn.
+- Produces the AF messages, options, and session id that the route passes to
+  `agent.run(...)`.
+- **Stores** each newly minted response id for the session it was just
+  resolved from, via `state.set_session(response_id, session)` after
+  `agent.run(...)` has updated the session.
+  OpenAI's `previous_response_id` rotates every turn *by design* — it lets a
+  caller continue from any earlier response, not just the latest one — so
+  every response id needs to stay independently resolvable, not just the
+  most recent.
+- Treats an unknown `conversation_id` as a request to create a new local
+  session. Your app can choose a stricter policy, such as requiring a separate
+  API to create new conversations before callers can continue them.
+
+`app:app` is a module-level FastAPI ASGI app; recommended local launch is
+Hypercorn.
+
+## Production readiness
+
+This is not a full-fledged production deployment. Before exposing this pattern
+to callers, add authentication and authorization at the infrastructure layer,
+the FastAPI app layer, or inside the route body.
+
+Session continuation deserves particular care: treat `previous_response_id` and
+`conversation_id` as untrusted request values, authorize the caller before
+loading or storing a session for those ids, and partition any durable session
+store by tenant/user as appropriate for your application.
+
+## Run
+
+```bash
+export FOUNDRY_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com
+export FOUNDRY_MODEL=gpt-5-nano
+az login
+
+uv sync
+uv run hypercorn app:app --bind 0.0.0.0:8000
+```
+
+Single-process for quick iteration:
+
+```bash
+uv run python app.py
+```
+
+## Call locally
+
+```bash
+uv sync --group dev
+
+# Plain OpenAI SDK call:
+uv run python call_server.py
+
+# The client intentionally omits `model`; the app chooses the backing deployment
+# from FOUNDRY_MODEL.
+
+# The script then sends two more turns, each continuing from the previous
+# turn's `response.id` as `previous_response_id`. The third turn asks about
+# the first turn's city, so it only succeeds if the server still remembers
+# that far back in the chain.
+
+# Same three-turn interaction through an Agent Framework Agent backed by
+# OpenAIChatClient:
+uv run python call_server_af.py
+```
+
+> This sample is **local-only** — no Dockerfile, no Foundry packaging.
@@ -0,0 +1,195 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Minimal Responses-only hosting sample with native FastAPI routes.
+
+This sample demonstrates the helper-first hosting shape:
+
+1. ``agent-framework-hosting-responses`` converts Responses request/response
+   payloads to and from Agent Framework run values.
+2. ``agent-framework-hosting`` owns shared execution state via
+   ``AgentState`` and ``SessionStore``.
+3. FastAPI owns the route, request parsing, policy decisions, and response
+   object.
+
+Production readiness
+---
+This sample is not a full-fledged production deployment. Before exposing this
+route to callers, add authentication and authorization at the infrastructure
+layer, the FastAPI app layer, or inside the route body.
+
+Session continuation deserves particular care: treat ``previous_response_id``
+and ``conversation_id`` as untrusted request values, authorize the caller
+before loading or storing a session for those ids, and partition durable session
+storage by tenant/user as appropriate for your application. See
+``README.md#production-readiness``.
+
+Unknown ``conversation_id`` values create a new local session in this sample.
+Your app can choose a different policy, such as requiring a separate API to
+create new conversations before callers can continue them.
+
+Run
+---
+``app`` is a module-level FastAPI ASGI app. Recommended local launch::
+
+    uv sync
+    az login
+    export FOUNDRY_PROJECT_ENDPOINT=https://<your-project>.services.ai.azure.com
+    export FOUNDRY_MODEL=gpt-5-nano
+    uv run hypercorn app:app --bind 0.0.0.0:8000
+
+Or use the ``__main__`` block (single-process Hypercorn) for quick
+iteration::
+
+    uv run python app.py
+
+Then call it::
+
+    uv run python call_server.py "What is the weather in Tokyo?"
+"""
+
+from __future__ import annotations
+
+import asyncio
+import os
+from collections.abc import AsyncIterator
+from pathlib import Path
+from typing import Annotated, Any, cast
+
+from agent_framework import Agent, FileHistoryProvider, ResponseStream, tool
+from agent_framework_foundry import FoundryChatClient
+from agent_framework_hosting import AgentState
+from agent_framework_hosting_responses import (
+    create_response_id,
+    responses_from_run,
+    responses_from_streaming_run,
+    responses_session_id,
+    responses_to_run,
+)
+from azure.identity.aio import DefaultAzureCredential
+from fastapi import Body, FastAPI, HTTPException
+from fastapi.responses import JSONResponse, StreamingResponse
+from hypercorn.asyncio import serve
+from hypercorn.config import Config
+
+SESSIONS_DIR = Path(__file__).resolve().parent / "storage" / "sessions"
+SESSIONS_DIR.mkdir(parents=True, exist_ok=True)
+
+
+@tool(approval_mode="never_require")
+def lookup_weather(
+    location: Annotated[str, "The city to look up weather for."],
+) -> str:
+    """Return a deterministic weather report for a city."""
+    high_temp = 5 + (sum(location.encode("utf-8")) % 21)
+    reports = {
+        "Seattle": f"Seattle is rainy with a high of {high_temp}°C.",
+        "Amsterdam": f"Amsterdam is cloudy with a high of {high_temp}°C.",
+        "Tokyo": f"Tokyo is clear with a high of {high_temp}°C.",
+    }
+    return reports.get(location, f"{location} is sunny with a high of {high_temp}°C.")
+
+
+def create_agent() -> Agent:
+    """Create the sample weather agent."""
+    return Agent(
+        client=FoundryChatClient(credential=DefaultAzureCredential()),
+        name="WeatherAgent",
+        instructions=(
+            "You are a friendly weather assistant. Use the lookup_weather tool "
+            "for any weather question and answer in one short sentence."
+        ),
+        tools=[lookup_weather],
+        context_providers=[FileHistoryProvider(SESSIONS_DIR)],
+        default_options={"store": False},
+    )
+
+
+app = FastAPI()
+state = AgentState(create_agent)
+
+ALLOWED_REQUEST_OPTIONS = frozenset({"max_tokens", "reasoning"})
+
+
+@app.post("/responses", response_model=None)
+async def responses(body: dict[str, Any] = Body(...)) -> JSONResponse | StreamingResponse:  # noqa: B008
+    """Handle one OpenAI Responses-shaped request."""
+    try:
+        run = responses_to_run(body)
+    except ValueError as exc:
+        raise HTTPException(status_code=400, detail=str(exc)) from exc
+    session_id = responses_session_id(body)
+    response_id = create_response_id()
+
+    # App-specific policy: allow only the request options this route is willing
+    # to honor. This denies tools, tool_choice, deployment/persistence fields,
+    # and all other caller-supplied options by default. Your app decides which
+    # options are allowed, altered, or denied.
+    options = {key: value for key, value in run["options"].items() if key in ALLOWED_REQUEST_OPTIONS}
+    options["reasoning"] = {"effort": "medium", "summary": "auto"}
+    options_for_run = cast(Any, options)
+
+    target = await state.get_target()
+    lookup_id = session_id or response_id
+    # An unknown `conversation_id` becomes a new session here. Production apps
+    # can choose to require a separate "create conversation" API instead.
+    session = await state.get_or_create_session(lookup_id)
+    if run["stream"]:
+        stream = target.run(
+            run["messages"],
+            stream=True,
+            session=session,
+            options=options_for_run,
+        )
+        if not isinstance(stream, ResponseStream):
+            raise HTTPException(status_code=500, detail="agent did not return a response stream")
+
+        async def stream_events() -> AsyncIterator[str]:
+            async for event in responses_from_streaming_run(
+                stream,
+                response_id=response_id,
+                session_id=session_id,
+            ):
+                yield event
+            # `agent.run(..., stream=True)` updates the session while the stream
+            # is consumed/finalized. Store it under the newly minted response id
+            # after finalization so a later `previous_response_id` can restore
+            # this exact continuation point.
+            await state.set_session(response_id, session)
+
+        return StreamingResponse(
+            stream_events(),
+            media_type="text/event-stream",
+        )
+
+    result = await target.run(
+        run["messages"],
+        session=session,
+        options=options_for_run,
+    )
+    # `agent.run(...)` updates the session. Store it under the newly minted
+    # response id after the run so `previous_response_id=response_id` continues
+    # from this exact point.
+    await state.set_session(response_id, session)
+    return JSONResponse(
+        responses_from_run(
+            result,
+            response_id=response_id,
+            session_id=session_id,
+        )
+    )
+
+
+async def main() -> None:
+    """Run the sample with Hypercorn for local development."""
+    config = Config()
+    config.bind = [f"0.0.0.0:{int(os.environ.get('PORT', '8000'))}"]
+    await serve(cast(Any, app), config)
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
+
+# Sample output:
+# User: What is the weather in Tokyo?
+# Agent: Tokyo is clear with a high of 18°C.
+# Response ID: resp_...
@@ -0,0 +1,63 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Local client for the local_responses sample.
+
+Posts to ``/responses`` using the standard ``openai`` SDK.
+
+Pass ``--previous-response-id <id>`` to continue a conversation by its
+``response.id`` (returned in the prior response).
+
+Start the server first (in another shell)::
+
+    uv run python app.py
+
+Then::
+
+    uv run python call_server.py
+
+The script sends two follow-up turns, each continuing from the previous
+turn's ``response.id`` as ``previous_response_id``. The third turn asks about
+information from the *first* turn only, so it also exercises session
+continuity across a rotating response id chain, not just a single hop.
+"""
+
+from __future__ import annotations
+
+from openai import OpenAI
+
+BASE_URL = "http://127.0.0.1:8000"
+PROMPT = "What is the weather in Tokyo?"
+FOLLOW_UP_PROMPT = "And what about Amsterdam?"
+THIRD_PROMPT = "Which of the two cities we just discussed is warmer?"
+
+
+def main() -> None:
+    client = OpenAI(base_url=BASE_URL, api_key="not-needed")
+    response = client.responses.create(
+        input=PROMPT,
+    )
+    print(f"User: {PROMPT}")
+    print(f"Agent: {response.output_text}")
+    print(f"Response ID: {response.id}")
+
+    follow_up = client.responses.create(
+        input=FOLLOW_UP_PROMPT,
+        previous_response_id=response.id,
+    )
+    print()
+    print(f"User: {FOLLOW_UP_PROMPT}")
+    print(f"Agent: {follow_up.output_text}")
+    print(f"Response ID: {follow_up.id}")
+
+    third = client.responses.create(
+        input=THIRD_PROMPT,
+        previous_response_id=follow_up.id,
+    )
+    print()
+    print(f"User: {THIRD_PROMPT}")
+    print(f"Agent: {third.output_text}")
+    print(f"Response ID: {third.id}")
+
+
+if __name__ == "__main__":
+    main()
@@ -0,0 +1,59 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+"""Agent Framework agent client for the local_responses sample.
+
+Creates a local :class:`agent_framework.Agent` backed by
+:class:`agent_framework.openai.OpenAIChatClient` and points that client at the
+hosted ``/responses`` endpoint for all turns:
+
+1. ``What is the weather in Tokyo?``
+2. ``And what about Amsterdam?``
+3. ``Which of the two cities we just discussed is warmer?``
+
+All turns use the same :class:`agent_framework.AgentSession`; the first turn
+binds the hosted response id to the session, and later turns continue through
+that session via a chain of rotating ``previous_response_id`` values. The
+third turn only makes sense if the server still remembers the first turn, so
+it also exercises session continuity across that whole chain, not just a
+single hop.
+
+Start the server first (in another shell)::
+
+    uv run python app.py
+
+Then::
+
+    uv run python call_server_af.py
+"""
+
+from __future__ import annotations
+
+import asyncio
+
+from agent_framework import Agent
+from agent_framework.openai import OpenAIChatClient
+
+BASE_URL = "http://127.0.0.1:8000"
+PROMPTS = [
+    "What is the weather in Tokyo?",
+    "And what about Amsterdam?",
+    "Which of the two cities we just discussed is warmer?",
+]
+
+
+async def main() -> None:
+    agent = Agent(
+        client=OpenAIChatClient(base_url=BASE_URL, api_key="not-needed"),
+        name="HostedWeatherClient",
+    )
+    session = agent.create_session()
+
+    for prompt in PROMPTS:
+        print(f"User: {prompt}")
+        response = await agent.run(prompt, session=session)
+        print(f"Agent: {response.text}\n")
+        print(f"Response ID: {response.response_id}\n")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())
@@ -0,0 +1,28 @@
+[project]
+name = "agent-framework-hosting-sample-local-responses"
+version = "0.0.1"
+description = "Minimal Responses-only local hosting sample with native FastAPI routes."
+requires-python = ">=3.10"
+dependencies = [
+    "agent-framework-foundry",
+    "agent-framework-hosting",
+    "agent-framework-hosting-responses",
+    "azure-identity",
+    "aiohttp>=3.13.5",
+    "fastapi>=0.115.0,<0.138.1",
+    "hypercorn>=0.17",
+]
+
+[dependency-groups]
+dev = [
+    "agent-framework-openai",
+    "openai>=1.99",
+]
+
+[tool.uv]
+package = false
+
+[tool.uv.sources]
+agent-framework-hosting = { git = "https://github.com/microsoft/agent-framework.git", branch = "main", subdirectory = "python/packages/hosting" }
+agent-framework-hosting-responses = { git = "https://github.com/microsoft/agent-framework.git", branch = "main", subdirectory = "python/packages/hosting-responses" }
+agent-framework-openai = { git = "https://github.com/microsoft/agent-framework.git", branch = "main", subdirectory = "python/packages/openai" }
@@ -0,0 +1,2 @@
+*
+!.gitignore