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,291 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: accepted
+contact: markwallace
+date: 2025-08-06
+deciders: markwallace-microsoft, westey-m, quibitron
+consulted: shawnhenry, elijahstraight
+informed: 
+---
+
+# Agent Framework / Foundry SDK Alignment
+
+Agent Framework and Foundry SDK have overlapping functionality but serve different audiences & scenarios. 
+This specification clarifies the positioning of these SDKs to customers, what goes in each and when to use what. 
+
+- **Foundry SDK** is a thin-client SDK for accessing everything available in the agent service and is autogenerated from REST APIs in multiple languages 
+- **Agent Framework SDK** is general-purpose framework for agentic application development, where common agent abstractions enable creating and orchestrating heterogenous agent systems (across local & cloud)
+
+## What is the goal of this feature?
+
+Goals:
+- Developers can seamlessly combine Foundry and Agent Framework SDK's and there is no friction when using both SDKs at the same time
+- Developers can take advantage of the full capabilities supported by the Foundry SDK
+- Developers can create multi-agent orchestrations using Foundry and other agent types
+
+Success Metrics:
+- Complexity of basic samples is comparable to other agent frameworks
+- Developers can easily discover how to use Foundry Agents in Agent Framework multi-agent orchestrations
+
+## What is the problem being solved?
+
+- In Semantic Kernel the Foundry Agent support isn't integrated into the Foundry SDK so there is a disjointed developer UX
+- Customers are confused as to when they should use Foundry SDK versus Semantic Kernel
+
+
+## API Changes
+
+The proposed solution is to add helper methods which allow developers to either retrieve or create an `AIAgent` using a `PersistentAgentsClient` 
+
+- Retrieve an `AIAgent`
+    ```csharp
+    /// <summary>
+    /// Retrieves an existing server side agent, wrapped as a <see cref="ChatClientAgent"/> using the provided <see cref="PersistentAgentsClient"/>.
+    /// </summary>
+    /// <param name="persistentAgentsClient">The <see cref="PersistentAgentsClient"/> to create the <see cref="ChatClientAgent"/> with.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> for the persistent agent.</returns>
+    /// <param name="agentId"> The ID of the server side agent to create a <see cref="ChatClientAgent"/> for.</param>
+    /// <param name="chatOptions">Options that should apply to all runs of the agent.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> instance that can be used to perform operations on the persistent agent.</returns>
+    public static async Task<ChatClientAgent> GetAIAgentAsync(
+        this PersistentAgentsClient persistentAgentsClient,
+        string agentId,
+        ChatOptions? chatOptions = null,
+        CancellationToken cancellationToken = default)
+    ```
+- Create an `AIAgent`
+    ```csharp
+    /// <summary>
+    /// Creates a new server side agent using the provided <see cref="PersistentAgentsClient"/>.
+    /// </summary>
+    /// <param name="persistentAgentsClient">The <see cref="PersistentAgentsClient"/> to create the agent with.</param>
+    /// <param name="model">The model to be used by the agent.</param>
+    /// <param name="name">The name of the agent.</param>
+    /// <param name="description">The description of the agent.</param>
+    /// <param name="instructions">The instructions for the agent.</param>
+    /// <param name="tools">The tools to be used by the agent.</param>
+    /// <param name="toolResources">The resources for the tools.</param>
+    /// <param name="temperature">The temperature setting for the agent.</param>
+    /// <param name="topP">The top-p setting for the agent.</param>
+    /// <param name="responseFormat">The response format for the agent.</param>
+    /// <param name="metadata">The metadata for the agent.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> instance that can be used to perform operations on the newly created agent.</returns>
+    public static async Task<ChatClientAgent> CreateAIAgentAsync(
+        this PersistentAgentsClient persistentAgentsClient,
+        string model,
+        string? name = null,
+        string? description = null,
+        string? instructions = null,
+        IEnumerable<ToolDefinition>? tools = null,
+        ToolResources? toolResources = null,
+        float? temperature = null,
+        float? topP = null,
+        BinaryData? responseFormat = null,
+        IReadOnlyDictionary<string, string>? metadata = null,
+        CancellationToken cancellationToken = default)
+    ```
+- Additional overload using the M.E.AI types:
+    ```csharp
+    /// <summary>
+    /// Creates a new server side agent using the provided <see cref="PersistentAgentsClient"/>.
+    /// </summary>
+    /// <param name="persistentAgentsClient">The <see cref="PersistentAgentsClient"/> to create the agent with.</param>
+    /// <param name="model">The model to be used by the agent.</param>
+    /// <param name="name">The name of the agent.</param>
+    /// <param name="description">The description of the agent.</param>
+    /// <param name="instructions">The instructions for the agent.</param>
+    /// <param name="tools">The tools to be used by the agent.</param>
+    /// <param name="temperature">The temperature setting for the agent.</param>
+    /// <param name="topP">The top-p setting for the agent.</param>
+    /// <param name="responseFormat">The response format for the agent.</param>
+    /// <param name="metadata">The metadata for the agent.</param>
+    /// <param name="cancellationToken">The <see cref="CancellationToken"/> to monitor for cancellation requests. The default is <see cref="CancellationToken.None"/>.</param>
+    /// <returns>A <see cref="ChatClientAgent"/> instance that can be used to perform operations on the newly created agent.</returns>
+    public static async Task<ChatClientAgent> CreateAIAgentAsync(
+        this PersistentAgentsClient persistentAgentsClient,
+        string model,
+        string? name = null,
+        string? description = null,
+        string? instructions = null,
+        IEnumerable<AITool>? tools = null,
+        float? temperature = null,
+        float? topP = null,
+        BinaryData? responseFormat = null,
+        IReadOnlyDictionary<string, string>? metadata = null,
+        CancellationToken cancellationToken = default)
+    ```
+
+
+## E2E Code Samples
+
+### 1. Create and retrieve with Foundry SDK, run with Agent Framework
+
+- [Foundry SDK] Create a `PersistentAgentsClient`
+- [Foundry SDK] Create a `PersistentAgent` using the `PersistentAgentsClient`
+- [Foundry SDK] Retrieve an `AIAgent` using the `PersistentAgentsClient`
+- [Agent Framework SDK] Invoke the `AIAgent` instance and access response from the `AgentResponse` 
+- [Foundry SDK] Clean up the agent
+
+
+```csharp
+// Get a client to create server side agents with.
+var persistentAgentsClient = new PersistentAgentsClient(
+    TestConfiguration.AzureAI.Endpoint, new AzureCliCredential());
+
+// Create a persistent agent.
+var persistentAgentMetadata = await persistentAgentsClient.Administration.CreateAgentAsync(
+    model: TestConfiguration.AzureAI.DeploymentName!,
+    name: JokerName,
+    instructions: JokerInstructions);
+
+// Get the persistent agent we created in the previous step and expose it as an Agent Framework agent.
+AIAgent agent = await persistentAgentsClient.GetAIAgentAsync(persistentAgent.Value.Id);
+
+// Respond to user input.
+var input = "Tell me a joke about a pirate.";
+Console.WriteLine(input);
+Console.WriteLine(await agent.RunAsync(input));
+
+// Delete the persistent agent.
+await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
+```
+
+### 2. Create directly with Foundry SDK, run with Agent Framework
+
+- [Foundry SDK] Create a `PersistentAgentsClient`
+- [Foundry SDK] Create a `AIAgent` using the `PersistentAgentsClient`
+- [Agent Framework SDK] Invoke the `AIAgent` instance and access response from the `AgentResponse` 
+- [Foundry SDK] Clean up the agent
+
+```csharp
+// Get a client to create server side agents with.
+var persistentAgentsClient = new PersistentAgentsClient(
+    TestConfiguration.AzureAI.Endpoint, new AzureCliCredential());
+
+// Create a persistent agent and expose it as an Agent Framework agent.
+AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
+    model: TestConfiguration.AzureAI.DeploymentName!,
+    name: JokerName,
+    instructions: JokerInstructions);
+
+// Respond to user input.
+var input = "Tell me a joke about a pirate.";
+Console.WriteLine(input);
+Console.WriteLine(await agent.RunAsync(input));
+
+// Delete the persistent agent.
+await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
+```
+
+### 3. Create directly with Foundry SDK, run with conversation state using Agent Framework
+
+- [Foundry SDK] Create a `PersistentAgentsClient`
+- [Foundry SDK] Create a `AIAgent` using the `PersistentAgentsClient`
+- [Agent Framework SDK] Optionally create an `AgentThread` for the agent run
+- [Agent Framework SDK] Invoke the `AIAgent` instance and access response from the `AgentResponse` 
+- [Foundry SDK] Clean up the agent and the agent thread
+
+```csharp
+// Get a client to create server side agents with.
+var persistentAgentsClient = new PersistentAgentsClient(
+    TestConfiguration.AzureAI.Endpoint, new AzureCliCredential());
+
+// Create an Agent Framework agent.
+AIAgent agent = await persistentAgentsClient.CreateAIAgentAsync(
+    model: TestConfiguration.AzureAI.DeploymentName!,
+    name: JokerName,
+    instructions: JokerInstructions);
+
+// Start a new thread for the agent conversation.
+AgentThread thread = agent.GetNewThread();
+
+// Respond to user input.
+await RunAgentAsync("Tell me a joke about a pirate.");
+await RunAgentAsync("Now add some emojis to the joke.");
+
+// Local function to run agent and display the conversation messages for the thread.
+async Task RunAgentAsync(string input)
+{
+    Console.WriteLine(
+        $"""
+        User: {input}
+        Assistant:
+        {await agent.RunAsync(input, thread)}
+
+        """);
+}
+
+// Cleanup
+await persistentAgentsClient.Threads.DeleteThreadAsync(thread.ConversationId);
+await persistentAgentsClient.Administration.DeleteAgentAsync(agent.Id);
+```
+
+### 4. Create directly with Foundry SDK, orchestrate with Agent Framework
+
+- [Foundry SDK] Create a `PersistentAgentsClient`
+- [Foundry SDK] Create multiple `AIAgent` instances using the `PersistentAgentsClient`
+- [Agent Framework SDK] Create a `SequentialOrchestration` and add all of the agents to it
+- [Agent Framework SDK] Invoke the `SequentialOrchestration` instance and access response from the `AgentResponse` 
+- [Foundry SDK] Clean up the agents
+
+```csharp
+// Get a client to create server side agents with.
+var persistentAgentsClient = new PersistentAgentsClient(
+    TestConfiguration.AzureAI.Endpoint, new AzureCliCredential());
+var model = TestConfiguration.OpenAI.ChatModelId;
+
+// Define the agents
+AIAgent analystAgent =
+    await persistentAgentsClient.CreateAIAgentAsync(
+        model,
+        name: "Analyst",
+        instructions:
+        """
+        You are a marketing analyst. Given a product description, identify:
+        - Key features
+        - Target audience
+        - Unique selling points
+        """,
+        description: "An agent that extracts key concepts from a product description.");
+AIAgent writerAgent =
+    await persistentAgentsClient.CreateAIAgentAsync(
+        model,
+        name: "copywriter",
+        instructions:
+        """
+        You are a marketing copywriter. Given a block of text describing features, audience, and USPs,
+        compose a compelling marketing copy (like a newsletter section) that highlights these points.
+        Output should be short (around 150 words), output just the copy as a single text block.
+        """,
+        description: "An agent that writes a marketing copy based on the extracted concepts.");
+AIAgent editorAgent =
+    await persistentAgentsClient.CreateAIAgentAsync(
+        model,
+        name: "editor",
+        instructions:
+        """
+        You are an editor. Given the draft copy, correct grammar, improve clarity, ensure consistent tone,
+        give format and make it polished. Output the final improved copy as a single text block.
+        """,
+        description: "An agent that formats and proofreads the marketing copy.");
+
+// Define the orchestration
+SequentialOrchestration orchestration =
+    new(analystAgent, writerAgent, editorAgent)
+    {
+        LoggerFactory = this.LoggerFactory,
+    };
+
+// Run the orchestration
+string input = "An eco-friendly stainless steel water bottle that keeps drinks cold for 24 hours";
+Console.WriteLine($"\n# INPUT: {input}\n");
+AgentResponse result = await orchestration.RunAsync(input);
+Console.WriteLine($"\n# RESULT: {result}");
+
+// Cleanup
+await persistentAgentsClient.Administration.DeleteAgentAsync(analystAgent.Id);
+await persistentAgentsClient.Administration.DeleteAgentAsync(writerAgent.Id);
+await persistentAgentsClient.Administration.DeleteAgentAsync(editorAgent.Id);
+```
@@ -0,0 +1,348 @@
+---
+status: proposed
+contact: eavanvalkenburg
+date: 2026-07-08
+deciders: eavanvalkenburg
+---
+
+# Python protocol helpers and optional execution state
+
+## Scope
+
+This specification is the Python implementation plan for
+[ADR-0027](../decisions/0027-hosting-channels.md). It documents the helper-first v1 contract for Python hosting.
+
+The v1 contract is:
+
+- protocol packages expose helper functions that convert protocol-native input to Agent Framework run values;
+- protocol packages expose helper functions that convert Agent Framework run results or streams back to protocol-native
+  payloads or operations;
+- application/framework code owns routes, native SDK clients, authentication, command policy, webhooks, response status
+  codes, and outbound sends;
+- `agent-framework-hosting` provides small optional state holders for Agent Framework targets;
+- state helpers do not own web apps, route contribution, protocol dispatch, command projection, or native SDK calls.
+
+## Goals
+
+- Let apps expose agents and workflows from FastAPI, Starlette, Django, Azure Functions, native SDK webhooks, CLIs, and
+  tests without adopting a host/channel framework.
+- Keep protocol parsing and response formatting inside protocol packages.
+- Keep session continuity explicit and app-owned at the trust boundary.
+- Reuse Agent Framework primitives: `AgentSession`, `CheckpointStorage`, `Agent.run(...)`, `Workflow.run(...)`, and
+  `ResponseStream`.
+- Preserve full-fidelity Agent Framework results until a protocol helper renders them.
+
+## Non-goals for v1
+
+### App-owned in v1
+
+The app builder owns these concerns with normal web-framework, SDK, platform, or application code:
+
+- authentication, authorization policy, and allowlists;
+- deciding whether identities across protocols map to the same `session_id`;
+- non-originating sends using native SDK clients;
+- background work, durable execution, retry, and replay when app code owns the work;
+- routing between multiple agents.
+
+The helper-first model makes app-owned linking and non-originating delivery easier than the old host/channel model because
+app code already owns the native SDK clients, authenticated caller context, session id selection, and outbound sends.
+
+### Future framework work
+
+The following require a separate reviewed design before becoming reusable framework features:
+
+- reusable cross-channel identity linking;
+- framework-owned proactive or non-originating delivery;
+- fan-out, multicast, selected-channel, active-channel, or all-linked delivery;
+- framework-owned delivery observability, dead-letter handling, and replay semantics;
+- cross-channel confidentiality and link policy.
+
+[ADR-0028](../decisions/0028-hosting-linking-multicast-enhancements.md) tracks possible follow-up work in this area and
+must be aligned with the helper-first model before implementation. Old vocabulary such as `IdentityLinker`,
+`ResponseTarget`, `ChannelPush`, `ChannelPushCodec`, `DurableTaskRunner`, `RetryPolicy`, and `LinkPolicy` is not v1 API.
+
+## Packages
+
+| Package | Import surface | v1 helper-first contents |
+|---|---|---|
+| `agent-framework-hosting` | `agent_framework_hosting` | `AgentState`, `WorkflowState`, `SessionStore`, and run-argument `TypedDict`s. |
+| `agent-framework-hosting-responses` | `agent_framework_hosting_responses` | Responses helpers: request parsing, session id extraction, response id creation, response rendering, streaming rendering. |
+| Future protocol packages | e.g. `agent_framework_hosting_telegram` | Protocol-specific helpers such as `telegram_to_run(...)`, `telegram_from_run(...)`, `telegram_session_id(...)`, and command/media helpers when useful. |
+
+The core hosting package must not depend on protocol SDKs. Protocol packages may depend on their native protocol SDKs if
+needed, but helper functions should stay usable from plain app code and tests.
+
+## Helper naming and families
+
+Helper names are protocol-specific. Avoid a generic `protocol_to_run(...)` public surface.
+
+Protocol packages may provide the following helper families when the protocol has the concept:
+
+| Helper family | Shape | Purpose |
+| --- | --- | --- |
+| Run conversion | `<protocol>_to_run(...)` | Convert one protocol-native call/update/request into `Agent.run` or `Workflow.run` values. |
+| Final rendering | `<protocol>_from_run(...)` | Convert a final `AgentResponse` or workflow result into protocol-native response payloads or operations. |
+| Stream rendering | `<protocol>_from_streaming_run(...)` | Convert `ResponseStream` or workflow updates into protocol-native events or operations. |
+| Session id extraction | `<protocol>_session_id(...)` | Extract the protocol's natural continuation/partition key from the call, if present. |
+| Command/action parsing | `<protocol>_command(...)` | Parse a protocol-native command/action/operation name without deciding app policy. |
+
+Examples:
+
+- `responses_to_run(...)`, `responses_from_run(...)`, `responses_from_streaming_run(...)`,
+  `responses_session_id(...)`;
+- `telegram_to_run(...)`, `telegram_from_run(...)`, `telegram_from_streaming_run(...)`,
+  `telegram_session_id(...)`, `telegram_command(...)`;
+- `activity_to_run(...)`, `activity_from_run(...)`, `activity_session_id(...)`, `activity_command(...)`;
+- `discord_to_run(...)`, `discord_from_run(...)`, `discord_session_id(...)`, `discord_command(...)`.
+
+This table is a naming guide, not a required checklist. A protocol package should add only the helpers that match native
+protocol concepts and current samples.
+
+Protocol-specific helpers may also exist for native details such as `telegram_chat_id(...)`,
+`telegram_callback_query_id(...)`, `telegram_media_file_id(...)`, `discord_interaction_id(...)`, `a2a_task_id(...)`,
+`a2a_context_id(...)`, or MCP tool/prompt/resource helpers. These helpers should stay side-effect-free. App/native SDK
+code performs acknowledgements, sends/edits messages, resolves protected file URLs, applies rate limits, and registers
+handlers.
+
+## `agent-framework-hosting` state helpers
+
+### `SessionStore`
+
+`SessionStore` is an in-memory async lookup:
+
+```python
+class SessionStore:
+    async def get(self, session_id: str) -> AgentSession | None: ...
+    async def set(self, session_id: str, session: AgentSession) -> None: ...
+    async def delete(self, session_id: str) -> None: ...
+```
+
+The store does not create sessions. It stores `session_id -> AgentSession` values supplied by callers.
+
+The built-in store has no TTL or eviction. This is intentional for local/dev and simple process-local scenarios: protocols
+such as OpenAI Responses can continue from any prior response id. Durable or multi-replica deployments should provide a
+durable store and their own TTL/eviction policy.
+
+### `AgentState`
+
+`AgentState` holds an agent target and an optional `SessionStore`:
+
+```python
+state = AgentState(agent)
+state = AgentState(create_agent)
+state = AgentState(create_agent, cache_target=False)
+```
+
+The target may be:
+
+- a `SupportsAgentRun` instance;
+- a synchronous factory;
+- an asynchronous factory;
+- an awaitable target.
+
+`AgentState` provides:
+
+- `await get_target()`;
+- synchronous `target` only after a target is already available/resolved;
+- `session_store`;
+- `await get_or_create_session(session_id)`;
+- `await set_session(session_id, session)`.
+
+`get_or_create_session(...)` resolves the target and calls `target.create_session(session_id=...)` only when the store has
+no session for that id.
+
+Apps must store the post-run session explicitly after `agent.run(...)` or stream finalization:
+
+```python
+session = await state.get_or_create_session(session_id)
+target = await state.get_target()
+result = await target.run(messages, session=session, options=options)
+await state.set_session(response_id, session)
+```
+
+### `WorkflowState`
+
+`WorkflowState` resolves a workflow target. It does not own checkpoint storage.
+
+The target may be:
+
+- a `Workflow` instance;
+- a `WorkflowBuilder` or other object with `build() -> Workflow`;
+- a synchronous factory;
+- an asynchronous factory;
+- an awaitable target.
+
+`WorkflowState` provides:
+
+- `await get_target()`;
+- synchronous `target` only after a target is already available/resolved.
+
+Workflow checkpointing uses Agent Framework's existing `CheckpointStorage` abstraction directly. Apps that need
+per-session workflow resume should keep an app-owned cursor such as `session_id -> checkpoint_id`. When the app uses
+file-backed cursor storage, the file-based checkpoint storage should share the same app storage root and should be
+scoped to the current authenticated user/tenant/session bucket, for example
+`storage/checkpoints/<session-bucket>/` beside `storage/checkpoint_cursors.json`:
+
+```python
+# session_id must already be authenticated and authorized for this caller
+target = await workflow_state.get_target()
+checkpoint_id = await checkpoint_cursor_store.get(session_id)
+if checkpoint_id is None:
+    result = await target.run(message=workflow_input, checkpoint_storage=checkpoint_storage)
+else:
+    result = await target.run(checkpoint_id=checkpoint_id, checkpoint_storage=checkpoint_storage)
+latest = await checkpoint_storage.get_latest(workflow_name=target.name)
+if latest is not None:
+    await checkpoint_cursor_store.set(session_id, latest.checkpoint_id)
+```
+
+`Workflow.run(...)` does not currently emit a checkpoint id on `WorkflowRunResult` or normal workflow events by default.
+The runner receives checkpoint ids internally from `CheckpointStorage.save(...)`. Apps that own the storage can query
+`get_latest(workflow_name=...)` after the run if they need to update a cursor.
+
+## `agent-framework-hosting-responses`
+
+The Responses package provides the helper-first surface for OpenAI Responses-shaped requests.
+
+### Request helpers
+
+- `messages_from_responses_input(input) -> list[Message]`
+- `responses_to_run(body) -> AgentRunArgs`
+- `responses_session_id(body) -> str | None`
+- `create_response_id() -> str`
+
+`responses_to_run(...)` returns values corresponding to `Agent.run(...)`:
+
+```python
+run = responses_to_run(body)
+messages = run["messages"]
+options = run["options"]
+stream = run["stream"]
+```
+
+It excludes protocol transport/session fields from `options` and remaps known Responses option names such as
+`max_output_tokens -> max_tokens`.
+
+`responses_session_id(...)` returns:
+
+- `previous_response_id` when present (`resp_*`);
+- otherwise `conversation_id` when present (`conv_*`);
+- otherwise `None`.
+
+The helper only extracts the candidate key. App code decides whether to trust and use that key.
+
+### Response helpers
+
+- `responses_from_run(result, *, response_id, session_id=None) -> dict[str, Any]`
+- `responses_from_streaming_run(stream, *, response_id, session_id=None) -> AsyncIterator[str]`
+
+`responses_from_run(...)` renders a full Responses JSON payload from an `AgentResponse`. It renders the full set of
+OpenAI Responses output item types supported by Agent Framework content.
+
+`responses_from_streaming_run(...)` renders Server-Sent Event strings for a `ResponseStream`. It emits a created event,
+text deltas, and a completed event. The final completed payload is produced through `responses_from_run(...)`; the helper
+also preserves the model id observed on streaming updates when the finalized `AgentResponse` no longer carries raw model
+metadata.
+
+## Security responsibilities
+
+Protocol helper packages parse and render. They do not authenticate callers, authorize access to state, or decide which
+side effects are allowed.
+
+Application code that uses these helpers is responsible for:
+
+- authenticating the caller through the app's normal mechanism before using protocol-provided ids;
+- authorizing any caller-supplied session, checkpoint, task, context, conversation, thread, or response id before loading
+  state for it;
+- binding externally supplied ids to the authenticated user, tenant, workspace, installation, or chat context before
+  using them as `SessionStore` keys or checkpoint cursor keys;
+- treating `<protocol>_session_id(...)` results as untrusted candidate keys until that ownership check has passed;
+- keeping platform-provided isolation helpers fail-closed outside their trusted hosting environment;
+- authorizing command/action effects such as reset, cancel, approve, submit, or tool invocation after parsing them;
+- opting in explicitly before resolving protected media/resource/file URLs and passing them to a remote model provider;
+- persisting post-run session or checkpoint state only after `agent.run(...)`, `workflow.run(...)`, or stream finalization
+  has updated that state.
+
+## Persistent versus transient hosting
+
+The application builder decides whether the server is persistent or transient.
+
+- Persistent single-process apps, such as a long-running container or web app, may use in-memory state for local
+  development or simple deployments. Multi-replica persistent apps still need durable state for continuity.
+- Transient apps, such as Azure Functions, Foundry Hosted Agents, or any environment where process memory is not a
+  reliable boundary, must not rely on in-memory `SessionStore` state between calls. They need a durable session store or
+  a service-owned continuation id.
+- Workflow hosts must choose an explicit `CheckpointStorage` and, when they need per-session resume, a durable
+  `session_id -> checkpoint_id` cursor. File-backed checkpoint storage and file-backed cursor storage should live under
+  the same app storage root, with checkpoints scoped to the current authenticated user/tenant/session bucket so a
+  "latest checkpoint" lookup cannot cross conversations. In-process workflow state and in-memory checkpoint cursors do
+  not survive transient execution.
+
+## Minimal FastAPI Responses shape
+
+This is the shape the local Responses sample should demonstrate. It is not an app framework.
+
+```python
+from collections.abc import AsyncIterator
+
+from agent_framework import ResponseStream
+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 fastapi import Body, FastAPI, HTTPException
+from fastapi.responses import JSONResponse, StreamingResponse
+
+app = FastAPI()
+state = AgentState(create_agent)
+
+
+@app.post("/responses", response_model=None)
+async def responses(body: dict = Body(...)) -> JSONResponse | StreamingResponse:
+    run = responses_to_run(body)
+    candidate_session_id = responses_session_id(body)
+    response_id = create_response_id()
+
+    # Verify this caller owns candidate_session_id before loading it.
+    session_id = candidate_session_id or response_id
+    session = await state.get_or_create_session(session_id)
+    target = await state.get_target()
+
+    if run["stream"]:
+        stream = target.run(run["messages"], stream=True, session=session, options=run["options"])
+        if not isinstance(stream, ResponseStream):
+            raise HTTPException(status_code=500, detail="agent did not return a response stream")
+
+        async def events() -> AsyncIterator[str]:
+            async for event in responses_from_streaming_run(
+                stream,
+                response_id=response_id,
+                session_id=candidate_session_id,
+            ):
+                yield event
+            await state.set_session(response_id, session)
+
+        return StreamingResponse(events(), media_type="text/event-stream")
+
+    result = await target.run(run["messages"], session=session, options=run["options"])
+    await state.set_session(response_id, session)
+    return JSONResponse(responses_from_run(result, response_id=response_id, session_id=candidate_session_id))
+```
+
+## Validation
+
+Implementation validation must cover:
+
+- `SessionStore` plain get/set/delete behavior;
+- `AgentState` target resolution, target caching, and get-or-create session behavior;
+- `WorkflowState` target resolution for direct workflows, factories, `WorkflowBuilder`, and orchestration-style builders;
+- Responses request parsing and option remapping;
+- Responses session id extraction;
+- Responses response rendering, including rich output item mapping;
+- Responses streaming SSE rendering;
+- HTTP round-trip tests showing a native FastAPI route using `AgentState` and Responses helpers;
+- sample type checking for the local Responses sample.
@@ -0,0 +1,75 @@
+---
+# These are optional elements. Feel free to remove any of them.
+status: {proposed | rejected | accepted | deprecated | … | superseded by [SPEC-0001](0001-spec.md)}
+contact: {person proposing the ADR}
+date: {YYYY-MM-DD when the decision was last updated}
+deciders: {list everyone involved in the decision}
+consulted: {list everyone whose opinions are sought (typically subject-matter experts); and with whom there is a two-way communication}
+informed: {list everyone who is kept up-to-date on progress; and with whom there is a one-way communication}
+---
+
+# {short title of solved problem and solution}
+
+## What is the goal of this feature?
+
+Make sure to cover:
+1. What is the value we are providing to users
+1. Include one success metric
+1. Implementation free description of outcome
+
+Consult PM on this.
+
+For example:
+
+We want users to be able to refer to external Azure resources easily when consuming them in other features like indexes, agents,
+and evaluations. We know we're successful when 40% of project client users are using connections.
+
+## What is the problem being solved?
+
+Make sure to cover:
+1. Why is this hard today?
+1. Customer pain points?
+1. Reducing system complexity (maintenance costs, latency, etc)?
+
+Consult PM on this.
+
+For example:
+
+Today, users have to understand control plane vs data plane endpoints and use multiple packages to stitch their application
+code together. This makes using our product confusing and also increases the number of dependencies a customer will have
+in their code.
+
+## API Changes
+
+List all new API changes
+
+## E2E Code Samples
+
+Include python or C# examples of how you expect this feature to be used with other things in our system.
+
+For example:
+
+This connection name is unique across the resource. Given a resource name, system should be able to unambiguously resolve a
+connection name. A connection name can be used to pass along connection details to individual features. Services will be able to parse this ID and use it to access the underlying resource. The below example shows how a connection can be used to create a dataset.
+
+```python
+client.datasets.create_dataset(
+    name="evaluation_dataset",
+    file="myblob/product1.pdf",
+    connection = "my-azure-blob-connection"
+)
+```
+
+How to use a connection when creating an `AzureAISearchIndex`
+
+```python
+from azure.ai.projects.models import AzureAISearchIndex
+
+azure_ai_search_index = AzureAISearchIndex(
+    name="azure-search-index",
+    connection="my-ai-search-connection",
+    index_name="my-index-in-azure-search",
+)
+
+created_index = client.indexes.create_index(azure_ai_search_index)
+```