Improve samples

2026-06-16 21:04:09 +08:00 · 2026-04-20 16:29:53 -07:00
parent 0fcd71dbeb
commit 3fb7a03e05
27 changed files with 392 additions and 113 deletions
@@ -0,0 +1,56 @@
+# Foundry Hosted Agents Samples
+
+This directory contains samples that demonstrate how to use the Agent Framework to host agents on Foundry with different capabilities and configurations. Each sample includes a README with instructions on how to set up, run, and interact with the agent.
+
+Read more about Foundry Hosted Agents [here](https://learn.microsoft.com/en-us/azure/foundry/agents/concepts/hosted-agents).
+
+## Environment setup
+
+1. Navigate to the sample directory you want to run. For example:
+
+   ```bash
+   python -m venv .venv
+
+   # Windows
+   .venv\Scripts\Activate
+
+   # macOS/Linux
+   source .venv/bin/activate
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Create a `.env` file with your Foundry configuration following the `env.example` file in the sample.
+
+4. Make sure you are logged in with the Azure CLI:
+
+   ```bash
+   az login
+   ```
+
+## Deploying to a Docker container
+
+Navigate to the sample directory and build the Docker image:
+
+```bash
+docker build -t hosted-agent-sample .
+```
+
+Run the container, passing in the required environment variables:
+
+```bash
+docker run -p 8088:8088 \
+  -e FOUNDRY_PROJECT_ENDPOINT=<your-endpoint> \
+  -e FOUNDRY_MODEL=<your-model> \
+  hosted-agent-sample
+```
+
+The server will be available at `http://localhost:8088`. You can send requests using the same `curl` command shown above.
+
+## Deploying to Foundry
+
+Follow this [guide](https://learn.microsoft.com/en-us/azure/foundry/agents/how-to/deploy-hosted-agent?tabs=bash#configure-your-agent) to deploy your agent to Foundry.
@@ -1,13 +0,0 @@
-# Basic example of hosting an agent with the `invocations` API
-
-Run the following command to start the server:
-
-```bash
-python main.py
-```
-
-Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example:
-
-```bash
-curl -X POST http://localhost:8088/invocations -H "Content-Type: application/json" -d '{"message": "Hi!"}'
-```
@@ -0,0 +1,6 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
@@ -0,0 +1,2 @@
+FOUNDRY_PROJECT_ENDPOINT= "..."
+MODEL_DEPLOYMENT_NAME="..."
@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY . user_agent/
+WORKDIR /app/user_agent
+
+RUN if [ -f requirements.txt ]; then \
+        pip install -r requirements.txt; \
+    else \
+        echo "No requirements.txt found"; \
+    fi
+
+EXPOSE 8088
+
+CMD ["python", "main.py"]
@@ -0,0 +1,44 @@
+# Basic example of hosting an agent with the `invocations` API
+
+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
+### Interacting with the agent
+
+Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example:
+
+```bash
+curl -X POST http://localhost:8088/invocations -i -H "Content-Type: application/json" -d '{"message": "Hi"}'
+```
+
+The server will respond with a JSON object containing the response text. The `-i` flag in the `curl` command includes the HTTP response headers in the output, which includes the session ID that can be used for multi-turn conversations. Here is an example of the response:
+
+```
+HTTP/1.1 200 
+content-length: 34
+content-type: application/json
+x-agent-invocation-id: ec04d020-a0e7-441e-ae83-db75635a9f83
+x-agent-session-id: 9370b9d4-cd13-4436-a57f-03b843ac0e17
+x-platform-server: azure-ai-agentserver-core/2.0.0a20260410006 (python/3.12)
+date: Fri, 17 Apr 2026 23:46:44 GMT
+server: hypercorn-h11
+
+{"response":"Hi! How can I help?"}
+```
+
+### Multi-turn conversation
+
+To have a multi-turn conversation with the agent, take the session ID from the response headers of the previous request and include it in URL parameters for the next request. For example:
+
+```bash
+curl -X POST http://localhost:8088/invocations?agent_session_id=9370b9d4-cd13-4436-a57f-03b843ac0e17 -i -H "Content-Type: application/json" -d '{"message": "How are you?"}'
+```
@@ -0,0 +1,23 @@
+name: agent-framework-agent-basic-invocations
+description: >
+  A basic Agent Framework agent hosted by Foundry.
+metadata:
+  tags:
+    - Agent Framework
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Invocations Protocol
+    - Streaming
+template:
+  name: agent-framework-agent-basic-invocations
+  kind: hosted
+  protocols:
+    - protocol: invocations
+      version: 1.0.0
+  environment_variables:
+    - name: MODEL_DEPLOYMENT_NAME
+      value: "{{MODEL_DEPLOYMENT_NAME}}"
+resources:
+  - kind: model
+    id: gpt-4.1-mini
+    name: MODEL_DEPLOYMENT_NAME
@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: agent-framework-agent-basic-invocations
+protocols:
+  - protocol: invocations
+    version: 1.0.0
+resources:
+  cpu: '0.25'
+  memory: '0.5Gi'
@@ -15,7 +15,7 @@ load_dotenv()
 def main():
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
-        model=os.environ["FOUNDRY_MODEL"],
+        model=os.environ["MODEL_DEPLOYMENT_NAME"],
        credential=AzureCliCredential(),
    )

@@ -0,0 +1,6 @@
+.venv
+__pycache__
+*.pyc
+*.pyo
+*.pyd
+.Python
@@ -0,0 +1,2 @@
+FOUNDRY_PROJECT_ENDPOINT= "..."
+MODEL_DEPLOYMENT_NAME="..."
@@ -0,0 +1,16 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+COPY . user_agent/
+WORKDIR /app/user_agent
+
+RUN if [ -f requirements.txt ]; then \
+        pip install -r requirements.txt; \
+    else \
+        echo "No requirements.txt found"; \
+    fi
+
+EXPOSE 8088
+
+CMD ["python", "main.py"]
@@ -0,0 +1,44 @@
+# Basic example of hosting an agent with the `invocations` API
+
+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
+### Interacting with the agent
+
+Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example:
+
+```bash
+curl -X POST http://localhost:8088/invocations -i -H "Content-Type: application/json" -d '{"message": "Hi"}'
+```
+
+The server will respond with a JSON object containing the response text. The `-i` flag in the `curl` command includes the HTTP response headers in the output, which includes the session ID that can be used for multi-turn conversations. Here is an example of the response:
+
+```
+HTTP/1.1 200 
+content-length: 34
+content-type: application/json
+x-agent-invocation-id: ec04d020-a0e7-441e-ae83-db75635a9f83
+x-agent-session-id: 9370b9d4-cd13-4436-a57f-03b843ac0e17
+x-platform-server: azure-ai-agentserver-core/2.0.0a20260410006 (python/3.12)
+date: Fri, 17 Apr 2026 23:46:44 GMT
+server: hypercorn-h11
+
+{"response":"Hi! How can I help?"}
+```
+
+### Multi-turn conversation
+
+To have a multi-turn conversation with the agent, take the session ID from the response headers of the previous request and include it in URL parameters for the next request. For example:
+
+```bash
+curl -X POST http://localhost:8088/invocations?agent_session_id=9370b9d4-cd13-4436-a57f-03b843ac0e17 -i -H "Content-Type: application/json" -d '{"message": "How are you?"}'
+```
@@ -0,0 +1,23 @@
+name: agent-framework-agent-basic-invocations
+description: >
+  A basic Agent Framework agent hosted by Foundry.
+metadata:
+  tags:
+    - Agent Framework
+    - AI Agent Hosting
+    - Azure AI AgentServer
+    - Invocations Protocol
+    - Streaming
+template:
+  name: agent-framework-agent-basic-invocations
+  kind: hosted
+  protocols:
+    - protocol: invocations
+      version: 1.0.0
+  environment_variables:
+    - name: MODEL_DEPLOYMENT_NAME
+      value: "{{MODEL_DEPLOYMENT_NAME}}"
+resources:
+  - kind: model
+    id: gpt-4.1-mini
+    name: MODEL_DEPLOYMENT_NAME
@@ -0,0 +1,9 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/microsoft/AgentSchema/refs/heads/main/schemas/v1.0/ContainerAgent.yaml
+kind: hosted
+name: agent-framework-agent-basic-invocations
+protocols:
+  - protocol: invocations
+    version: 1.0.0
+resources:
+  cpu: '0.25'
+  memory: '0.5Gi'
@@ -0,0 +1,74 @@
+# Copyright (c) Microsoft. All rights reserved.
+
+import os
+from collections.abc import AsyncGenerator
+
+from agent_framework import Agent, AgentSession
+from agent_framework.foundry import FoundryChatClient
+from azure.ai.agentserver.invocations import InvocationAgentServerHost
+from azure.identity import DefaultAzureCredential
+from dotenv import load_dotenv
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response, StreamingResponse
+
+# Load environment variables from .env file
+load_dotenv()
+
+
+# In-memory session store — keyed by session ID.
+# WARNING: This is lost on restart. Use durable storage in production.
+_sessions: dict[str, AgentSession] = {}
+
+# Create the agent
+client = FoundryChatClient(
+    project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
+    model=os.environ["MODEL_DEPLOYMENT_NAME"],
+    credential=DefaultAzureCredential(),
+)
+
+agent = Agent(
+    client=client,
+    instructions="You are a friendly assistant. Keep your answers brief.",
+    # History will be managed by the hosting infrastructure, thus there
+    # is no need to store history by the service. Learn more at:
+    # https://developers.openai.com/api/reference/resources/responses/methods/create
+    default_options={"store": False},
+)
+
+app = InvocationAgentServerHost()
+
+
+@app.invoke_handler
+async def handle_invoke(request: Request):
+    """Handle streaming multi-turn chat with Azure OpenAI via SSE."""
+    data = await request.json()
+    session_id = request.state.session_id
+
+    stream = data.get("stream", False)
+    user_message = data.get("message", None)
+    if user_message is None:
+        error = "Missing 'message' in request"
+        if stream:
+            return StreamingResponse(content=error, status_code=400)
+        return Response(content=error, status_code=400)
+
+    session = _sessions.setdefault(session_id, AgentSession(session_id=session_id))
+
+    if stream:
+
+        async def stream_response() -> AsyncGenerator[str]:
+            async for update in agent.run(user_message, session=session, stream=True):
+                yield update.text
+
+        return StreamingResponse(
+            stream_response(),
+            media_type="text/event-stream",
+            headers={"Cache-Control": "no-cache", "Connection": "keep-alive"},
+        )
+
+    response = await agent.run([user_message], session=session, stream=stream)
+    return JSONResponse({"response": response.text})
+
+
+if __name__ == "__main__":
+    app.run()
@@ -0,0 +1,2 @@
+agent-framework
+azure-ai-agentserver-invocations
@@ -0,0 +1,8 @@
+# Hosting agents with Foundry Hosting and the `invocations` API
+
+This folder contains a list of samples that show how to host agents using the `invocations` API and deploy them to Foundry Hosting.
+
+| Sample | Description |
+| --- | --- |
+| [01_basic](./01_basic) | A basic example of hosting an agent with the `invocations` API and carrying on a multi-turn conversation. |
+| [02_break_glass](./02-break-glass) | An example of hosting an agent with the `invocations` API and a "break glass" scenario where you can create your own `invoke_handler` to handle specific types of invocations. |
@@ -2,6 +2,18 @@

 This agent only contains an instruction (personal). It's the most basic agent with an LLM and no tools.

+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
 ## Interacting with the agent

 Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example:
@@ -10,12 +22,6 @@ Send a POST request to the server with a JSON body containing a "message" field
 curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "Hi"}'
 ```

-### Invoke with `azd`
-
-```bash
-azd ai agent invoke --local "Hi"
-```
-
 ## Multi-turn conversation

 To have a multi-turn conversation with the agent, include the previous response id in the request body. For example:
@@ -23,11 +29,3 @@ To have a multi-turn conversation with the agent, include the previous response
 ```bash
 curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "How are you?", "previous_response_id": "REPLACE_WITH_PREVIOUS_RESPONSE_ID"}'
 ```
-
-Invoke with `azd`:
-
-```bash
-azd ai agent invoke --local "Hi!" --conversation-id "my_conv"
-
-azd ai agent invoke --local "How are you?" --conversation-id "my_conv"
-```
@@ -4,6 +4,18 @@ This agent is equipped with with a function tool and a local shell tool.

 > We recommend deploying this sample on a local container or to Foundry Hosting because the agent has access to a local shell tool, which can run arbitrary commands on the machine.

+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
 ## Interacting with the agent

 Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example:
@@ -13,11 +25,3 @@ curl -X POST http://localhost:8088/responses -H "Content-Type: application/json"

 curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "List the files in the current directory."}'
 ```
-
-Invoke with `azd`:
-
-```bash
-azd ai agent invoke --local "What is the weather in Seattle?"
-
-azd ai agent invoke --local "List the files in the current directory."
-```
@@ -1,4 +1,4 @@
 FOUNDRY_PROJECT_ENDPOINT="..."
 MODEL_DEPLOYMENT_NAME="..."
-FOUNDRY_AGENT_TOOLBOX_NAME="..."
+TOOLBOX_NAME="..."
 GITHUB_PAT="..."
@@ -4,6 +4,18 @@ This agent is equipped with a GitHub MCP server and a Foundry Toolbox, which are

 > Note that there are other ways to interact with Foundry toolboxes. Using it as a MCP is just one of the options.

+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
 ## Interacting with the agent

 Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example:
@@ -11,9 +23,3 @@ Send a POST request to the server with a JSON body containing a "message" field
 ```bash
 curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "List all the repositories I own on GitHub."}'
 ```
-
-Invoke with `azd`:
-
-```bash
-azd ai agent invoke --local "List all the repositories I own on GitHub."
-```
@@ -32,7 +32,7 @@ def main():

    # Foundry Toolbox as a MCP tool
    project_endpoint = os.environ["FOUNDRY_PROJECT_ENDPOINT"]
-    toolbox_name = os.environ["FOUNDRY_AGENT_TOOLBOX_NAME"]
+    toolbox_name = os.environ["TOOLBOX_NAME"]
    toolbox_endpoint = f"{project_endpoint.rstrip('/')}/toolboxes/{toolbox_name}/mcp?api-version=v1"
    http_client = httpx.AsyncClient(auth=ToolboxAuth(), headers={"Foundry-Features": "Toolboxes=V1Preview"})
    foundry_mcp_tool = MCPStreamableHTTPTool(
@@ -2,6 +2,18 @@

 This sample demonstrates how to host a workflow using the `responses` API.

+## Running the server locally
+
+### Environment setup
+
+Follow the instructions in the [Environment setup](../../README.md#environment-setup) section of the README in the parent directory to set up your environment and install dependencies.
+
+Run the following command to start the server:
+
+```bash
+python main.py
+```
+
 ## Interacting with the agent

 Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example:
@@ -9,9 +21,3 @@ Send a POST request to the server with a JSON body containing a "message" field
 ```bash
 curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "Create a slogan for a new electric SUV that is affordable and fun to drive."}'
 ```
-
-Invoke with `azd`:
-
-```bash
-azd ai agent invoke --local "Create a slogan for a new electric SUV that is affordable and fun to drive."
-```
@@ -4,7 +4,6 @@ import os

 from agent_framework import Agent, AgentExecutor, WorkflowBuilder
 from agent_framework.foundry import FoundryChatClient
-from agent_framework.orchestrations import GroupChatState
 from agent_framework_foundry_hosting import ResponsesHostServer
 from azure.identity import AzureCliCredential
 from dotenv import load_dotenv
@@ -13,13 +12,6 @@ from dotenv import load_dotenv
 load_dotenv()


-def round_robin_selector(state: GroupChatState) -> str:
-    """A round-robin selector function that picks the next speaker based on the current round index."""
-
-    participant_names = list(state.participants.keys())
-    return participant_names[state.current_round % len(participant_names)]
-
-
 def main():
    client = FoundryChatClient(
        project_endpoint=os.environ["FOUNDRY_PROJECT_ENDPOINT"],
@@ -8,58 +8,4 @@ This folder contains a list of samples that show how to host agents using the `r
 | [02_local_tools](./02_local_tools) | An example of hosting an agent with the `responses` API and local tools including a function tool and a local shell tool. |
 | [03_remote_mcp](./03_remote_mcp) | An example of hosting an agent with the `responses` API and remote MCPs, including a GitHub MCP server and a Foundry Toolboox. |
 | [04_workflows](./04_workflows) | An example of hosting a workflow with the `responses` API. |
-
-## Running the server locally
-
-Navigate to the sample directory and run the following command to start the server:
-
-```bash
-python main.py
-```
-
-## Interacting with the agent
-
-There two ways to interact with the agent: sending HTTP requests to the server or using the `azd` CLI:
-
-### Invoke with `azd`
-
-```bash
-azd ai agent invoke --local "Hi"
-```
-
-### Sending HTTP requests
-
-Send a POST request to the server with a JSON body containing a "message" field to interact with the agent. For example:
-
-```bash
-curl -X POST http://localhost:8088/responses -H "Content-Type: application/json" -d '{"input": "Hi"}'
-```
-
-> See the individual samples for more examples of interacting with the agent.
-
-## Deploying to a Docker container
-
-Navigate to the sample directory and build the Docker image:
-
-```bash
-docker build -t hosted-agent-sample .
-```
-
-Run the container, passing in the required environment variables:
-
-```bash
-docker run -p 8088:8088 \
-  -e FOUNDRY_PROJECT_ENDPOINT=<your-endpoint> \
-  -e FOUNDRY_MODEL=<your-model> \
-  hosted-agent-sample
-```
-
-The server will be available at `http://localhost:8088`. You can send requests using the same `curl` command shown above.
-
-## Deploying to Foundry
-
-TODO
-
-## Using the deployed agent in Agent Framework
-
-After deploying the agent, you can also try to use the agent in Agent Framework. Refer to the [using_deployed_agent.py](./using_deployed_agent.py) sample for an example of how to do this.
+| [using_deployed_agent.py](./using_deployed_agent.py) | An example of how to use the deployed agent in Agent Framework. |