rkttu · August 19, 2026 07:12
diff --git a/.env.example b/.env.example
 # Foundry project endpoint — auto-injected in hosted containers.
 # Only set manually when running the agent locally.
 # FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>

 # Model deployment name — must match a deployment in your Foundry project.
 AZURE_AI_MODEL_DEPLOYMENT_NAME=

 # Application Insights — auto-injected in hosted containers.
 # Set for local telemetry (optional but recommended).
 # APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...
diff --git a/.gitignore b/.gitignore
 # ─────────────────────────────────────────────────────────────────────────
 #  Build output
 #
 #  `deploy.py` stages and zips inside a temp directory, so it never dirties
 #  the source tree. But running `uv pip install --target` or `uv export -o`
 #  by hand does, and so does packaging the sample as a real project. The
 #  patterns below cover both cases.
 # ─────────────────────────────────────────────────────────────────────────
 build/
 dist/
 sdist/
 target/
 out/
 *.egg-info/
 .eggs/

 # Common `--target` / `-o` directory names used ad hoc
 vendor/
 _vendor/
 site-packages/
 publish/
 publish-*/
 app-publish/
 linux-x64/
 bundle/

 # Packaging output that can land loose in the tree
 *.zip
 *.tar
 *.tar.gz
 *.tgz
 *.whl

 # Exported dependency lists — regenerate with `uv export --script`
 requirements.txt
 requirements-*.txt
 constraints.txt

 # uv / packaging leftovers
 .uv/
 uv-cache/
 *.py.lock
 pip-log.txt
 pip-delete-this-directory.txt

 # ─────────────────────────────────────────────────────────────────────────
 #  Python runtime artifacts
 # ─────────────────────────────────────────────────────────────────────────
 __pycache__/
 *.py[cod]
 *$py.class
 *.so
 *.pyd
 .Python

 # Virtual environments
 .venv/
 venv/
 env/
 ENV/

 # Test and type-checker caches
 .pytest_cache/
 .mypy_cache/
 .ruff_cache/
 .pytype/
 .tox/
 .nox/
 .coverage
 .coverage.*
 htmlcov/
 coverage.xml
 .hypothesis/

 # ─────────────────────────────────────────────────────────────────────────
 #  Secrets and local configuration
 # ─────────────────────────────────────────────────────────────────────────
 .env
 .env.*
 !.env.example
 *.local.json
 secrets.json
 *.pfx
 *.p12
 *.key
 *.pem

 # ─────────────────────────────────────────────────────────────────────────
 #  Azure tooling
 # ─────────────────────────────────────────────────────────────────────────
 .azure/
 .azd/
 azd.env

 # ─────────────────────────────────────────────────────────────────────────
 #  IDE and editor
 # ─────────────────────────────────────────────────────────────────────────
 .vs/
 .vscode/*
 !.vscode/extensions.json
 !.vscode/launch.json
 !.vscode/settings.json
 !.vscode/tasks.json
 .idea/
 *.swp
 *.swo
 *~

 # ─────────────────────────────────────────────────────────────────────────
 #  OS junk
 # ─────────────────────────────────────────────────────────────────────────
 Thumbs.db
 ehthumbs.db
 Desktop.ini
 $RECYCLE.BIN/
 .DS_Store
 .DS_Store?
 ._*
 .Spotlight-V100
 .Trashes

 # ─────────────────────────────────────────────────────────────────────────
 #  Scratch
 # ─────────────────────────────────────────────────────────────────────────
 *.tmp
 *.temp
 *.bak
 *.orig
 *.rej
 tmp/
 temp/
 scratch/
diff --git a/README.ko.md b/README.ko.md
diff --git a/README.md b/README.md
diff --git a/agent_lg.py b/agent_lg.py
 #!/usr/bin/env -S uv run --script

 # /// script
 # requires-python = ">=3.13,<3.14"
 # dependencies = [
 #     "agent-framework-foundry==1.10.1",
 #     "agent-framework-foundry-hosting==1.0.0b260813",
 #     "azure-identity",
 #     "python-dotenv",
 # ]
 #
 # [tool.uv]
 # # The Foundry hosting packages ship as pre-releases, and they pull in Azure SDK
 # # dependencies that are themselves pinned to pre-release ranges. uv rejects
 # # pre-releases by default, and its narrower "explicit" mode only covers markers
 # # written here — not the transitive ones — so the whole resolution has to opt in.
 # prerelease = "allow"
 # ///

 """Hello World — Agent Framework Responses agent for Python.

 To deploy this hosted agent, follow the steps below.

 1. Install uv and the Azure CLI on the computer where you intend to proceed with
   the deployment.
 2. Log in using the `az login` command, and then verify that the token is
   successfully obtained using the
   `az account get-access-token --scope https://ai.azure.com/.default` command.
 3. Deploy the model to be used on the MS Foundry portal. Then, identify the name
   of the deployed model and assign it to the `FOUNDRY_MODEL_NAME` environment
   variable.
 4. Obtain the Foundry project endpoint URL. Assign this URL to the
   `FOUNDRY_PROJECT_ENDPOINT` environment variable.
 5. `uv run deploy.py <script file name> [agent name to expose to MS Foundry]`

 Minimal hosted agent that uses the Microsoft Agent Framework (`agent_framework`)
 to create an `Agent` backed by a Foundry model, then hosts it using
 `ResponsesHostServer` from `agent-framework-foundry-hosting`.

 This sample demonstrates the simplest possible Agent Framework integration: the
 agent framework manages the LLM call, conversation history, and response
 lifecycle automatically — there is no response handler to implement.
 `ResponsesHostServer.run()` handles the HTTP contract, port binding, health
 probes, SSE lifecycle, and OpenTelemetry tracing.

 Multi-turn conversation works automatically: on each request the framework
 rebuilds the conversation history from prior turns. Pass `previous_response_id`
 from one response as the input to the next call to maintain conversation
 context. Locally, history is stored in-process (lost on restart); when hosted by
 Foundry it uses durable server-side storage.

 Required environment variables:
  FOUNDRY_PROJECT_ENDPOINT        — Foundry project endpoint (auto-injected in
                                    hosted containers)
  AZURE_AI_MODEL_DEPLOYMENT_NAME  — Model deployment name (set by `deploy.py`)

 See `agent_lg.py` for the same agent built on LangGraph; it deploys the same way.

 Usage:
  uv run agent_msaf.py

  # Turn 1 — invoke the agent:
  curl -sS -X POST http://localhost:8088/responses \
    -H "Content-Type: application/json" \
    -d '{"input": "What is Microsoft Foundry?", "stream": false}' | jq .

  # Turn 2 — follow up using the id from the previous response:
  curl -sS -X POST http://localhost:8088/responses \
    -H "Content-Type: application/json" \
    -d '{"input": "Can you summarize that?", "previous_response_id": "<id>", "stream": false}' | jq .
 """

 import os
 import sys

 from agent_framework import Agent
 from agent_framework.foundry import FoundryChatClient, ResponsesHostServer
 from azure.identity.aio import DefaultAzureCredential
 from dotenv import load_dotenv

 # Load environment variables from a .env file if present (for local development).
 # load_dotenv() walks up from this file's directory and never clobbers a value
 # that is already set in the process environment.
 load_dotenv()

 if not os.environ.get("APPLICATIONINSIGHTS_CONNECTION_STRING"):
    print(
        "[WARNING] APPLICATIONINSIGHTS_CONNECTION_STRING not set — traces will not be sent "
        "to Application Insights. Set it to enable local telemetry. "
        "(This variable is auto-injected in hosted Foundry containers — do not set it "
        "in the deployed agent's environment.)",
        file=sys.stderr,
    )

 project_endpoint = os.environ.get("FOUNDRY_PROJECT_ENDPOINT")
 if not project_endpoint:
    raise RuntimeError("FOUNDRY_PROJECT_ENDPOINT environment variable is not set.")

 deployment = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME")
 if not deployment:
    raise RuntimeError("AZURE_AI_MODEL_DEPLOYMENT_NAME environment variable is not set.")

 # Create an Agent backed by a Foundry model.
 # The agent framework manages the LLM call, conversation sessions, and response
 # lifecycle. FoundryChatClient talks to the project over the async Azure SDK, so
 # it takes an async credential — token refresh must not block the event loop.
 agent = Agent(
    FoundryChatClient(
        project_endpoint=project_endpoint,
        model=deployment,
        credential=DefaultAzureCredential(),
    ),
    instructions="You are a helpful AI assistant. Be concise and informative.",
    name="hello-world",
    description="A minimal Hello World agent using the Agent Framework",
 )

 # ResponsesHostServer.run() auto-configures:
 #   - the ASGI server on port 8088 (or the PORT environment variable)
 #   - GET /readiness health probe
 #   - OpenTelemetry traces and metrics
 #   - x-platform-server response header
 ResponsesHostServer(agent).run()
diff --git a/agent_msaf.py b/agent_msaf.py
 #!/usr/bin/env -S uv run --script

 # /// script
 # requires-python = ">=3.13,<3.14"
 # dependencies = [
 #     "agent-framework-foundry==1.10.1",
 #     "agent-framework-foundry-hosting==1.0.0b260813",
 #     "azure-identity",
 #     "python-dotenv",
 # ]
 #
 # [tool.uv]
 # # The Foundry hosting packages ship as pre-releases, and they pull in Azure SDK
 # # dependencies that are themselves pinned to pre-release ranges. uv rejects
 # # pre-releases by default, and its narrower "explicit" mode only covers markers
 # # written here — not the transitive ones — so the whole resolution has to opt in.
 # prerelease = "allow"
 # ///

 """Hello World — Agent Framework Responses agent for Python.

 To deploy this hosted agent, follow the steps below.

 1. Install uv and the Azure CLI on the computer where you intend to proceed with
   the deployment.
 2. Log in using the `az login` command, and then verify that the token is
   successfully obtained using the
   `az account get-access-token --scope https://ai.azure.com/.default` command.
 3. Deploy the model to be used on the MS Foundry portal. Then, identify the name
   of the deployed model and assign it to the `FOUNDRY_MODEL_NAME` environment
   variable.
 4. Obtain the Foundry project endpoint URL. Assign this URL to the
   `FOUNDRY_PROJECT_ENDPOINT` environment variable.
 5. `uv run deploy.py <script file name> [agent name to expose to MS Foundry]`

 Minimal hosted agent that uses the Microsoft Agent Framework (`agent_framework`)
 to create an `Agent` backed by a Foundry model, then hosts it using
 `ResponsesHostServer` from `agent-framework-foundry-hosting`.

 This sample demonstrates the simplest possible Agent Framework integration: the
 agent framework manages the LLM call, conversation history, and response
 lifecycle automatically — there is no response handler to implement.
 `ResponsesHostServer.run()` handles the HTTP contract, port binding, health
 probes, SSE lifecycle, and OpenTelemetry tracing.

 Multi-turn conversation works automatically: on each request the framework
 rebuilds the conversation history from prior turns. Pass `previous_response_id`
 from one response as the input to the next call to maintain conversation
 context. Locally, history is stored in-process (lost on restart); when hosted by
 Foundry it uses durable server-side storage.

 Required environment variables:
  FOUNDRY_PROJECT_ENDPOINT        — Foundry project endpoint (auto-injected in
                                    hosted containers)
  AZURE_AI_MODEL_DEPLOYMENT_NAME  — Model deployment name (set by `deploy.py`)

 See `agent_lg.py` for the same agent built on LangGraph; it deploys the same way.

 Usage:
  uv run agent_msaf.py

  # Turn 1 — invoke the agent:
  curl -sS -X POST http://localhost:8088/responses \
    -H "Content-Type: application/json" \
    -d '{"input": "What is Microsoft Foundry?", "stream": false}' | jq .

  # Turn 2 — follow up using the id from the previous response:
  curl -sS -X POST http://localhost:8088/responses \
    -H "Content-Type: application/json" \
    -d '{"input": "Can you summarize that?", "previous_response_id": "<id>", "stream": false}' | jq .
 """

 import os
 import sys

 from agent_framework import Agent
 from agent_framework.foundry import FoundryChatClient, ResponsesHostServer
 from azure.identity.aio import DefaultAzureCredential
 from dotenv import load_dotenv

 # Load environment variables from a .env file if present (for local development).
 # load_dotenv() walks up from this file's directory and never clobbers a value
 # that is already set in the process environment.
 load_dotenv()

 if not os.environ.get("APPLICATIONINSIGHTS_CONNECTION_STRING"):
    print(
        "[WARNING] APPLICATIONINSIGHTS_CONNECTION_STRING not set — traces will not be sent "
        "to Application Insights. Set it to enable local telemetry. "
        "(This variable is auto-injected in hosted Foundry containers — do not set it "
        "in the deployed agent's environment.)",
        file=sys.stderr,
    )

 project_endpoint = os.environ.get("FOUNDRY_PROJECT_ENDPOINT")
 if not project_endpoint:
    raise RuntimeError("FOUNDRY_PROJECT_ENDPOINT environment variable is not set.")

 deployment = os.environ.get("AZURE_AI_MODEL_DEPLOYMENT_NAME")
 if not deployment:
    raise RuntimeError("AZURE_AI_MODEL_DEPLOYMENT_NAME environment variable is not set.")

 # Create an Agent backed by a Foundry model.
 # The agent framework manages the LLM call, conversation sessions, and response
 # lifecycle. FoundryChatClient talks to the project over the async Azure SDK, so
 # it takes an async credential — token refresh must not block the event loop.
 agent = Agent(
    FoundryChatClient(
        project_endpoint=project_endpoint,
        model=deployment,
        credential=DefaultAzureCredential(),
    ),
    instructions="You are a helpful AI assistant. Be concise and informative.",
    name="hello-world",
    description="A minimal Hello World agent using the Agent Framework",
 )

 # ResponsesHostServer.run() auto-configures:
 #   - the ASGI server on port 8088 (or the PORT environment variable)
 #   - GET /readiness health probe
 #   - OpenTelemetry traces and metrics
 #   - x-platform-server response header
 ResponsesHostServer(agent).run()
diff --git a/deploy.py b/deploy.py
 #!/usr/bin/env -S uv run --script

 # /// script
 # requires-python = ">=3.13,<3.14"
 # dependencies = [
 #     "azure-ai-projects==2.4.0",
 #     "azure-identity",
 #     # azure-ai-projects declares `openai>=2.8.0` with no upper bound, but it is
 #     # written against the 2.x client and imports httpx, which only the 2.x line
 #     # still pulls in — openai 3 moved to httpx2 and the import fails outright.
 #     "openai>=2.8,<3",
 # ]
 # ///

 # ════════════════════════════════════════════════════════════════════════
 #  Foundry hosted agent deployment script (uv single-file scripts only)
 #
 #  Usage:
 #    uv run deploy.py <agent.py> [agent-name]
 #
 #  Examples:
 #    uv run deploy.py agent_msaf.py
 #    uv run deploy.py agent_lg.py my-agent
 #
 #  This script runs on your local machine and performs, in order:
 #    publish -> create version -> wait for active -> route endpoint -> smoke test
 #
 #  ── Arguments ──────────────────────────────────────────────────────────
 #    [0] agent.py     Required. Path to the uv single-file script to deploy,
 #                     e.g. agent_msaf.py or agent_lg.py.
 #    [1] agent-name   Optional. Derived from the file name when omitted.
 #                     e.g. my_agent.py -> my-agent, main.py -> main
 #
 #    Publish output goes to a temporary directory under the system temp dir.
 #    It never pollutes the source tree, so no .gitignore entry is required
 #    for it. The directory is deleted on success and kept on failure so you
 #    can inspect the artifacts. The path is printed on the [publish] log line.
 #
 #  ── Environment variables ──────────────────────────────────────────────
 #
 #  [Required]
 #    FOUNDRY_PROJECT_ENDPOINT
 #        Data-plane endpoint of the target Foundry project.
 #        Format: https://<account>.services.ai.azure.com/api/projects/<project>
 #        Copy it from the project overview page in the portal.
 #
 #    FOUNDRY_MODEL_NAME
 #        Name of the model deployment the agent will call (e.g. gpt-5.6-terra).
 #        It must be a deployment that actually exists in the project. Note that
 #        this is the deployment name, not the model family name.
 #        The value is injected into the container as AZURE_AI_MODEL_DEPLOYMENT_NAME.
 #
 #  [Optional]
 #    FOUNDRY_AUTH                default "cli"
 #        "cli"     Use AzureCliCredential only, reusing your az login session.
 #        "default" Use the DefaultAzureCredential chain. For CI or managed identity.
 #
 #    FOUNDRY_TENANT_ID           no default
 #        Pins the target tenant when you are signed in to several of them.
 #
 #  ── Authentication ─────────────────────────────────────────────────────
 #    Sign in with az login to the tenant that owns the project beforehand.
 #    The Foundry Project Manager role is required at project scope.
 #
 #    Why the default is AzureCliCredential rather than DefaultAzureCredential:
 #    DefaultAzureCredential tries EnvironmentCredential first, so if
 #    AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_CLIENT_SECRET are left over on the
 #    machine it authenticates as that service principal and, on failure, breaks
 #    the chain (AADSTS700016 and friends). Your az login session is then never
 #    reached, which makes cli the safe choice for local deployments.
 #
 #    Check the signed-in tenant:
 #      az account show --query "{tenant:tenantId, user:user.name}" -o table
 #
 #  ── Note: do not confuse this with .env ────────────────────────────────
 #    The .env.example shipped with this sample is for running the agent itself
 #    locally. The AZURE_AI_MODEL_DEPLOYMENT_NAME and
 #    APPLICATIONINSIGHTS_CONNECTION_STRING values in it are injected by the
 #    platform in a deployed container, so this script does not read them.
 #    This script only uses the FOUNDRY_-prefixed variables listed above.
 #
 #  ── Example run (cmd) ──────────────────────────────────────────────────
 #    set FOUNDRY_PROJECT_ENDPOINT=https://myacct.services.ai.azure.com/api/projects/myproj
 #    set FOUNDRY_MODEL_NAME=gpt-5.6-terra
 #    uv run deploy.py agent_msaf.py
 #
 #  ── Example run (PowerShell) ───────────────────────────────────────────
 #    $env:FOUNDRY_PROJECT_ENDPOINT = 'https://myacct.services.ai.azure.com/api/projects/myproj'
 #    $env:FOUNDRY_MODEL_NAME       = 'gpt-5.6-terra'
 #    uv run deploy.py agent_msaf.py
 #
 # ════════════════════════════════════════════════════════════════════════

 import os
 import re
 import shutil
 import subprocess
 import sys
 import tempfile
 import time
 import zipfile
 from datetime import datetime, timedelta, timezone
 from pathlib import Path

 from azure.ai.projects import AIProjectClient
 from azure.ai.projects.models import (
    AgentEndpointConfig,
    AgentEndpointProtocol,
    AgentVersionStatus,
    CodeConfiguration,
    CodeDependencyResolution,
    FixedRatioVersionSelectionRule,
    HostedAgentDefinition,
    ProtocolConfiguration,
    ProtocolVersionRecord,
    ResponsesProtocolConfiguration,
    VersionSelector,
 )
 from azure.identity import AzureCliCredential, DefaultAzureCredential

 # The container image the agent runs in. PYTHON_RUNTIME picks the interpreter on
 # the Foundry side; TARGET_PLATFORM and TARGET_PYTHON pick the wheels bundled for
 # it. They have to agree, or the vendored binary extensions fail to import at
 # container start.
 #
 # manylinux_2_28 is the glibc 2.28 baseline (RHEL 8, Debian 10, Ubuntu 20.04 and
 # newer), which the Foundry runtime images satisfy. The older manylinux2014
 # (glibc 2.17) tag looks like the safer choice but is not: numpy 2.5 and a
 # growing number of packages no longer publish wheels for it, so a dependency
 # graph that reaches numpy — LangGraph's does — fails to resolve at all.
 PYTHON_RUNTIME = "python_3_13"
 TARGET_PYTHON = "3.13"
 TARGET_PLATFORM = "x86_64-manylinux_2_28"

 USAGE = """\
 Usage:
  uv run deploy.py <agent.py> [agent-name]

 Arguments:
  <agent.py>    Required. Path to the uv single-file script to deploy.
  [agent-name]  Optional. Derived from the file name when omitted
                (e.g. my_agent.py -> my-agent).

 For environment variables, see the comment block at the top of this file.\
 """


 # ── Helpers ─────────────────────────────────────────────────────────────
 def require(name: str) -> str:
    value = os.environ.get(name)
    if not value:
        raise RuntimeError(f"Environment variable {name} is not set.")
    return value


 def env(name: str, fallback: str) -> str:
    return os.environ.get(name) or fallback


 def to_agent_name(stem: str) -> str:
    """Convert a file name into a valid Foundry agent name.

    Rules: must start and end with a lowercase alphanumeric character, hyphens are
    allowed in between, and the length is capped at 63 characters.
    """
    name = re.sub(r"[^a-z0-9]", "-", stem.lower())
    name = re.sub(r"-{2,}", "-", name).strip("-")

    if len(name) > 63:
        name = name[:63].rstrip("-")

    if not name or not name[0].isalnum():
        raise RuntimeError(
            f"Could not derive a valid agent name from '{stem}'. "
            "Specify one explicitly as the second argument."
        )
    return name


 # The service's own rule: alphanumeric at both ends, hyphens allowed in between,
 # 63 characters max. Underscores are the trip-up — legal in a Python module name,
 # illegal here — so `agent_msaf.py` derives to `agent-msaf`, but the same name
 # typed by hand as `agent_msaf` is rejected.
 AGENT_NAME_PATTERN = re.compile(r"[A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?")


 def validate_agent_name(name: str) -> str:
    """Reject a name the service would reject, before anything expensive happens.

    An explicitly passed name is otherwise taken on trust and only checked
    server-side, which means the publish, the vendoring, the packing and a
    multi-megabyte upload all complete before the request comes back as an
    opaque `(invalid_parameters) ValidationError`. Checking it here costs
    nothing and fails on the first line of output instead.
    """
    if AGENT_NAME_PATTERN.fullmatch(name):
        return name

    try:
        suggestion = f" Try '{to_agent_name(name)}'."
    except RuntimeError:
        suggestion = ""

    raise RuntimeError(
        f"'{name}' is not a valid Foundry agent name. It must start and end with an "
        f"alphanumeric character, may contain hyphens in between, and is capped at "
        f"63 characters — underscores are not allowed.{suggestion}"
    )


 def run(*command: str) -> None:
    """Run a subprocess, letting its output stream straight to the console."""
    exit_code = subprocess.run(command).returncode
    if exit_code != 0:
        raise RuntimeError(f"{command[0]} {command[1]} failed (exit {exit_code}).")


 def capture(*command: str) -> str:
    """Run a subprocess and return its stdout. stderr still streams to the console."""
    result = subprocess.run(command, stdout=subprocess.PIPE, text=True, encoding="utf-8")
    if result.returncode != 0:
        raise RuntimeError(f"{command[0]} {command[1]} failed (exit {result.returncode}).")
    return result.stdout


 def main() -> int:
    # ── Arguments ───────────────────────────────────────────────────────
    args = sys.argv[1:]

    if not args or args[0] in ("-h", "--help", "/?"):
        print(USAGE)
        return 1 if not args else 0

    agent_source = Path(args[0]).resolve()

    if not agent_source.is_file():
        print(f"Source file not found: {agent_source}", file=sys.stderr)
        return 1

    if agent_source.suffix.lower() != ".py":
        print(f"Not a Python script (.py): {agent_source}", file=sys.stderr)
        return 1

    source_stem = agent_source.stem

    # The agent's dependencies live in its PEP 723 inline metadata block. Without
    # one there is nothing for `uv export` to resolve, and the agent would reach
    # the container with no packages bundled alongside it.
    head = agent_source.read_text(encoding="utf-8").splitlines()[:40]

    if not any(line.strip() == "# /// script" for line in head):
        print(f"[warn  ] {agent_source.name} is missing a PEP 723 '# /// script' metadata block.")

    if shutil.which("uv") is None:
        print(
            "uv not found on PATH. See https://docs.astral.sh/uv/ to install it.",
            file=sys.stderr,
        )
        return 1

    # ── Configuration ───────────────────────────────────────────────────
    # require: raises immediately when unset. env: falls back to the second argument.
    project_endpoint = require("FOUNDRY_PROJECT_ENDPOINT")  # required
    model_name = require("FOUNDRY_MODEL_NAME")  # required

    # Agent name: explicit argument first, otherwise derived from the file name.
    # Either way it is valid before it leaves this line — a derived name is valid
    # by construction, and an explicit one is checked against the same rule.
    agent_name = validate_agent_name(args[1]) if len(args) > 1 else to_agent_name(source_stem)

    # Publish output goes to a temporary directory. What ultimately matters is the
    # result deployed to Foundry; the local artifacts are useless once uploaded, and
    # this keeps the source tree clean. mkdtemp always hands back a fresh empty
    # directory, so stale artifacts can never end up in the zip and no pre-cleanup
    # logic is needed.
    publish_dir = Path(tempfile.mkdtemp(prefix=f"foundry-{source_stem}-"))
    stage_dir = publish_dir / "app"
    stage_dir.mkdir()

    print(f"[target] {agent_source.name}")
    print(f"[deploy] agent name : {agent_name}  (used in the invocation URL)")

    # ── 1. Publish the agent itself ─────────────────────────────────────
    print(f"[publish] -> {publish_dir}")

    # Resolve the PEP 723 metadata block into a pinned requirements list. This is
    # the uv equivalent of restoring a project file: the inline dependencies plus
    # everything they pull in, at exact versions.
    requirements = publish_dir / "requirements.txt"
    requirements.write_text(
        capture(
            "uv",
            "export",
            "--script",
            str(agent_source),
            "--format",
            "requirements-txt",
            "--no-hashes",
            "--no-header",
            "--no-annotate",
        ),
        encoding="utf-8",
    )

    # Vendor those packages for the container's platform, not this machine's.
    # --python-platform / --python-version cross-resolve the wheels the way
    # `dotnet publish -r linux-x64` cross-publishes; without them a Windows or
    # macOS build silently bundles binary extensions the container cannot load.
    # --only-binary :all: is what turns "no wheel for that platform" into an error
    # here instead of a source build against the wrong interpreter.
    run(
        "uv",
        "pip",
        "install",
        "-r",
        str(requirements),
        "--target",
        str(stage_dir),
        "--python-version",
        TARGET_PYTHON,
        "--python-platform",
        TARGET_PLATFORM,
        "--only-binary",
        ":all:",
        "--link-mode",
        "copy",
    )

    # ── 2. Place the entry point ────────────────────────────────────────
    # The script sits at the root of the bundle, next to the vendored packages, so
    # `python <name>.py` puts that directory first on sys.path and the imports
    # resolve with no PYTHONPATH involved. The flip side of that layout is that the
    # script's own name enters the module namespace: a script named azure.py or
    # json.py would shadow a real module and fail at import time — surfacing as a
    # 424 session_not_ready on the first invocation, long after this script exited.
    # Both collisions are checked here instead.
    if source_stem in sys.stdlib_module_names:
        raise RuntimeError(
            f"'{agent_source.name}' shadows the standard library module '{source_stem}'. "
            "Rename the script."
        )

    if (stage_dir / source_stem).is_dir() or (stage_dir / f"{source_stem}.py").exists():
        raise RuntimeError(
            f"'{agent_source.name}' shadows the bundled package '{source_stem}'. "
            "Rename the script."
        )

    entry_script = agent_source.name
    shutil.copy2(agent_source, stage_dir / entry_script)

    print(f"[deploy] entry point: python {entry_script}  (container-internal only)")

    # ── 3. Pack the bundle ──────────────────────────────────────────────
    # The zip is the container's file system, so its contents sit at the root — no
    # wrapper directory. `bin/` holds console-script launchers generated for THIS
    # machine (.exe shims on Windows); the container only ever runs the entry point
    # above, so they are dead weight and are dropped, along with uv's own install
    # lock and any bytecode cache.
    code_zip = publish_dir / "code.zip"
    file_count = 0

    def is_bundled(relative: Path) -> bool:
        return (
            relative.parts[0] not in ("bin", ".lock")
            and "__pycache__" not in relative.parts
        )

    with zipfile.ZipFile(code_zip, "w", zipfile.ZIP_DEFLATED) as archive:
        for path in sorted(stage_dir.rglob("*")):
            if not path.is_file():
                continue
            relative = path.relative_to(stage_dir)
            if not is_bundled(relative):
                continue
            archive.write(path, relative.as_posix())
            file_count += 1

    print(f"[pack  ] {file_count} files, {code_zip.stat().st_size / 1024 / 1024:.1f} MiB")

    # ── 4. Agent definition ─────────────────────────────────────────────
    definition = HostedAgentDefinition(
        cpu="0.5",
        memory="1Gi",
        protocol_versions=[
            ProtocolVersionRecord(protocol=AgentEndpointProtocol.RESPONSES, version="2.0.0")
        ],
        code_configuration=CodeConfiguration(
            runtime=PYTHON_RUNTIME,
            entry_point=["python", entry_script],
            # Bundled: run the uploaded tree as-is. No server-side build is
            # involved, so neither inline script metadata nor private indexes are
            # a problem.
            dependency_resolution=CodeDependencyResolution.BUNDLED,
        ),
        # FOUNDRY_PROJECT_ENDPOINT is a reserved variable injected by the platform,
        # so we do not set it here.
        environment_variables={"AZURE_AI_MODEL_DEPLOYMENT_NAME": model_name},
    )

    # ── Authentication ──────────────────────────────────────────────────
    # DefaultAzureCredential is a chain and EnvironmentCredential ranks ahead of
    # AzureCliCredential. If AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_CLIENT_SECRET
    # are left over, it tries the service principal first and, on failure, raises
    # ClientAuthenticationError rather than falling through, which breaks the chain
    # on the spot. Your az login session is then never reached (AADSTS700016 and
    # friends).
    leftover_spn = os.environ.get("AZURE_CLIENT_ID")
    tenant_id = os.environ.get("FOUNDRY_TENANT_ID")
    auth_mode = env("FOUNDRY_AUTH", "cli").lower()

    if auth_mode == "cli":
        # Default for local deployment. Uses only the az login session, so the
        # result is deterministic.
        credential = AzureCliCredential(tenant_id=tenant_id)
    elif auth_mode == "default":
        # For CI and similar, where a service principal or managed identity is
        # needed.
        credential = DefaultAzureCredential(
            **({"interactive_browser_tenant_id": tenant_id} if tenant_id else {})
        )
    else:
        raise RuntimeError(f"Invalid FOUNDRY_AUTH value: '{auth_mode}'. Use 'cli' or 'default'.")

    if auth_mode == "default" and leftover_spn:
        print(
            f"[warn  ] AZURE_CLIENT_ID={leftover_spn} is set, so authentication starts with that "
            "service principal. Run with FOUNDRY_AUTH=cli to use your az login session instead."
        )

    print(f"[auth  ] {auth_mode}{'' if tenant_id is None else f' (tenant {tenant_id})'}")

    # Preflight. Catch authentication failures here rather than deep inside the API
    # pipeline. Note: az account show only reads the local profile, so it succeeds
    # even when the session is dead. Only acquiring a token actually verifies it.
    try:
        probe = credential.get_token("https://ai.azure.com/.default")
        expires = datetime.fromtimestamp(probe.expires_on, tz=timezone.utc).astimezone()
        print(f"[auth  ] token acquired (expires {expires:%Y-%m-%d %H:%M})")
    except Exception as ex:
        raise RuntimeError(
            f"Failed to acquire a token (mode={auth_mode}).\n"
            "\n"
            "Run the following command directly to diagnose the cause:\n"
            "  az account get-access-token --scope https://ai.azure.com/.default\n"
            "\n"
            "Common causes:\n"
            "  - Expired refresh token. az account show only reads a local file, so it\n"
            "    succeeds even in this case.\n"
            "    Fix: az login --tenant <tenant-id>\n"
            "  - Azure CLI older than 2.80. Fix: az upgrade\n"
            "  - az not found from cmd.exe. Check: cmd /c az version\n"
            "\n"
            f"Original error: {ex}"
        ) from ex

    # allow_preview opts this client into the hosted-agent APIs — both the code
    # upload below and the per-agent OpenAI endpoint used by the smoke test.
    project_client = AIProjectClient(
        endpoint=project_endpoint,
        credential=credential,
        allow_preview=True,
    )

    # ── 5. Create the version ───────────────────────────────────────────
    # The SDK computes the SHA-256 of the stream for you. Versioning is
    # content-addressed, so when both the code and the definition are unchanged no
    # new version is created and the existing latest version is returned instead.
    # The stream's name must end in .zip — the SDK reads it to name the upload part.
    with code_zip.open("rb") as code:
        created = project_client.agents.create_version_from_code(
            agent_name,
            definition=definition,
            code=code,
        )

    print(f"[create] version {created.version}")

    # ── 6. Wait for active ──────────────────────────────────────────────
    # Bundled mode has no server-side build, so it finishes far faster than
    # remote_build.
    deadline = datetime.now(timezone.utc) + timedelta(minutes=10)

    while created.status not in (AgentVersionStatus.ACTIVE, AgentVersionStatus.FAILED):
        if datetime.now(timezone.utc) > deadline:
            raise TimeoutError("The version did not transition to active.")

        time.sleep(5)
        created = project_client.agents.get_version(agent_name, created.version)
        print(f"[status] {created.status}")

    if created.status == AgentVersionStatus.FAILED:
        raise RuntimeError(
            "Provisioning failed. Check the error on the version details page in the portal."
        )

    # The container runs as its own managed identity — not as whoever ran this
    # script — and that identity is what calls the model. It starts with no role
    # assignments, so printing it here turns granting one from a portal hunt into
    # a copy-paste. See the RBAC hint on the smoke-test failure below.
    identity = getattr(created, "instance_identity", None)
    principal_id = getattr(identity, "principal_id", None)

    if principal_id:
        print(f"[ident ] principal {principal_id}  (needs the Foundry User role)")

    # ── 7. Endpoint routing ─────────────────────────────────────────────
    # Traffic splitting is not supported yet; one version receives 100% at a time.
    project_client.agents.update_details(
        agent_name,
        agent_endpoint=AgentEndpointConfig(
            version_selector=VersionSelector(
                version_selection_rules=[
                    FixedRatioVersionSelectionRule(
                        agent_version=created.version,
                        traffic_percentage=100,
                    )
                ]
            ),
            protocol_configuration=ProtocolConfiguration(
                responses=ResponsesProtocolConfiguration()
            ),
        ),
    )

    print(f"[route ] {agent_name} -> version {created.version}")

    # ── 8. Smoke test ───────────────────────────────────────────────────
    # The container starts per session on the first invocation, which means entry
    # point errors and readiness failures only surface here. One call right after
    # deployment is mandatory.
    responses_client = project_client.get_openai_client(agent_name=agent_name)
    response = responses_client.responses.create(input="ping")

    # A container that failed at runtime still answers HTTP 200. The body is
    # either a Response carrying an `error`, or a bare {"code", "message"}
    # envelope that the OpenAI client parses into a Response all the same,
    # leaving `output` as None. Reading .output_text first turns both into
    # `TypeError: 'NoneType' object is not iterable` — a message that says
    # nothing about what actually broke — so the payload is unpacked before it is
    # trusted. Extra fields survive model_dump(), which is what makes the bare
    # envelope readable at all.
    payload = response.model_dump()
    failure = payload.get("error") or (
        {"code": payload.get("code"), "message": payload.get("message")}
        if payload.get("message")
        else None
    )

    if failure or not response.output:
        detail = str(failure or "the agent returned no output")

        # A permission fault is the one failure here that is not about the code at
        # all, and its message names an object id with no hint of what to do with
        # it. Recognise it and spell out the remedy.
        if any(
            marker in detail
            for marker in ("PermissionDenied", "does not have permissions", "Forbidden")
        ):
            hint = f"""
 This is an RBAC problem, not a code problem. The container runs as its own
 managed identity, which starts with no role assignments. Grant it the Foundry
 User role on the Foundry resource — that is the role covering the project data
 actions, including calling a model deployment:

  az role assignment create \\
    --assignee-object-id {principal_id or "<principal-id-printed-above>"} \\
    --assignee-principal-type ServicePrincipal \\
    --role 53ca6127-db72-4b80-b1b0-d745d6d5456d \\
    --scope /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<account>

 The role is passed by id because it was recently renamed: Foundry User was
 called Azure AI User, and both names are still in circulation. Do not reach for
 a role whose name begins with "Cognitive Services" — those target AI Services
 resources directly and do not apply to Foundry projects.

 Re-run this script once the assignment has propagated."""
        else:
            hint = f"""
 The version is Active and routed, so this is a fault inside the running
 container rather than a deployment problem. Its logs are on the agent's page in
 the portal. Reproduce it locally with:
  uv run {agent_source.name}"""

        raise RuntimeError(
            f"The agent deployed but failed on its first invocation.\n\n  {detail}\n{hint}"
        )

    print(f"[smoke ] {response.output_text}")

    # ── 9. Cleanup ──────────────────────────────────────────────────────
    # Delete the temporary directory only on the success path. If an exception is
    # raised along the way it is left behind so you can open the publish output and
    # trace the cause.
    shutil.rmtree(publish_dir)

    print("[done  ] deployment complete")

    print(
        "[info  ] Open the Microsoft Foundry portal (ai.azure.com) and run the prompts below "
        "to confirm the agent responds.\n"
        "\n"
        "What is Microsoft Foundry?\n"
        "Explain how hosted agents work in Foundry.\n"
        "Give me three ideas for a weekend project.\n"
        "Summarize the benefits of using the Agent Framework."
    )
    return 0


 if __name__ == "__main__":
    sys.exit(main())
	# Foundry project endpoint — auto-injected in hosted containers.
	# Only set manually when running the agent locally.
	# FOUNDRY_PROJECT_ENDPOINT=https://<account>.services.ai.azure.com/api/projects/<project>

	# Model deployment name — must match a deployment in your Foundry project.
	AZURE_AI_MODEL_DEPLOYMENT_NAME=

	# Application Insights — auto-injected in hosted containers.
	# Set for local telemetry (optional but recommended).
	# APPLICATIONINSIGHTS_CONNECTION_STRING=InstrumentationKey=...
	# ─────────────────────────────────────────────────────────────────────────
	# Build output
	#
	# `deploy.py` stages and zips inside a temp directory, so it never dirties
	# the source tree. But running `uv pip install --target` or `uv export -o`
	# by hand does, and so does packaging the sample as a real project. The
	# patterns below cover both cases.
	# ─────────────────────────────────────────────────────────────────────────
	build/
	dist/
	sdist/
	target/
	out/
	*.egg-info/
	.eggs/

	# Common `--target` / `-o` directory names used ad hoc
	vendor/
	_vendor/
	site-packages/
	publish/
	publish-*/
	app-publish/
	linux-x64/
	bundle/

	# Packaging output that can land loose in the tree
	*.zip
	*.tar
	*.tar.gz
	*.tgz
	*.whl

	# Exported dependency lists — regenerate with `uv export --script`
	requirements.txt
	requirements-*.txt
	constraints.txt

	# uv / packaging leftovers
	.uv/
	uv-cache/
	*.py.lock
	pip-log.txt
	pip-delete-this-directory.txt

	# ─────────────────────────────────────────────────────────────────────────
	# Python runtime artifacts
	# ─────────────────────────────────────────────────────────────────────────
	__pycache__/
	*.py[cod]
	*$py.class
	*.so
	*.pyd
	.Python

	# Virtual environments
	.venv/
	venv/
	env/
	ENV/

	# Test and type-checker caches
	.pytest_cache/
	.mypy_cache/
	.ruff_cache/
	.pytype/
	.tox/
	.nox/
	.coverage
	.coverage.*
	htmlcov/
	coverage.xml
	.hypothesis/

	# ─────────────────────────────────────────────────────────────────────────
	# Secrets and local configuration
	# ─────────────────────────────────────────────────────────────────────────
	.env
	.env.*
	!.env.example
	*.local.json
	secrets.json
	*.pfx
	*.p12
	*.key
	*.pem

	# ─────────────────────────────────────────────────────────────────────────
	# Azure tooling
	# ─────────────────────────────────────────────────────────────────────────
	.azure/
	.azd/
	azd.env

	# ─────────────────────────────────────────────────────────────────────────
	# IDE and editor
	# ─────────────────────────────────────────────────────────────────────────
	.vs/
	.vscode/*
	!.vscode/extensions.json
	!.vscode/launch.json
	!.vscode/settings.json
	!.vscode/tasks.json
	.idea/
	*.swp
	*.swo
	*~

	# ─────────────────────────────────────────────────────────────────────────
	# OS junk
	# ─────────────────────────────────────────────────────────────────────────
	Thumbs.db
	ehthumbs.db
	Desktop.ini
	$RECYCLE.BIN/
	.DS_Store
	.DS_Store?
	._*
	.Spotlight-V100
	.Trashes

	# ─────────────────────────────────────────────────────────────────────────
	# Scratch
	# ─────────────────────────────────────────────────────────────────────────
	*.tmp
	*.temp
	*.bak
	*.orig
	*.rej
	tmp/
	temp/
	scratch/
파일	역할
`agent_msaf.py`	Microsoft Agent Framework 기반 에이전트.
`agent_lg.py`	동일한 에이전트의 LangGraph 버전.
`deploy.py`	로컬 배포 스크립트. publish → 버전 생성 → active 대기 → 엔드포인트 라우팅 → 스모크 테스트 순으로 진행합니다. 두 에이전트 중 아무거나 인수로 받습니다.
`.env.example`	에이전트를 로컬에서 띄울 때 쓰는 템플릿. `.env`로 복사해서 사용합니다.
	경로	역할 할당 필요
`agent_msaf.py`	`POST /openai/v1/responses`	아니오
`agent_lg.py`	`POST /openai/v1/chat/completions`	예
	`agent_msaf.py`	`agent_lg.py`
프레임워크	Microsoft Agent Framework	LangGraph
에이전트 객체	`Agent(FoundryChatClient(...), instructions=...)`	`create_agent(model, tools=[], system_prompt=...)` → `CompiledStateGraph`
호스트 어댑터	`ResponsesHostServer(agent).run()`	`from_langgraph(graph).run(port=...)`
호스팅 패키지	`agent-framework-foundry-hosting`	`azure-ai-agentserver-langgraph`
모델 클라이언트	`FoundryChatClient`(프로젝트와 직접 통신)	프로젝트의 `AsyncOpenAI` 클라이언트를 감싼 `ChatOpenAI`
번들 크기	압축 약 19 MiB	압축 약 45 MiB
수신 포트	`PORT`를 직접 읽음	`DEFAULT_AD_PORT`를 읽으므로, 스크립트가 `PORT`를 명시적으로 전달
변수	필수	기본값	설명
`FOUNDRY_PROJECT_ENDPOINT`	예	—	대상 프로젝트의 데이터 플레인 엔드포인트. 포털의 프로젝트 개요 페이지에서 복사합니다.
`FOUNDRY_MODEL_NAME`	예	—	모델 배포 이름. 컨테이너에 `AZURE_AI_MODEL_DEPLOYMENT_NAME`으로 주입됩니다.
`FOUNDRY_AUTH`	아니오	`cli`	`cli`는 `AzureCliCredential`만 사용합니다. `default`는 `DefaultAzureCredential` 체인을 사용합니다(CI / 관리 ID용).
`FOUNDRY_TENANT_ID`	아니오	—	여러 테넌트에 로그인되어 있을 때 대상 테넌트를 고정합니다.
변수	필수	설명
`FOUNDRY_PROJECT_ENDPOINT`	예	호스팅 환경에서는 플랫폼이 자동 주입합니다. 로컬 실행 시에만 직접 설정하십시오.
`AZURE_AI_MODEL_DEPLOYMENT_NAME`	예	호스팅 시 `deploy.py`가 `FOUNDRY_MODEL_NAME` 값으로 설정합니다.
`APPLICATIONINSIGHTS_CONNECTION_STRING`	아니오	호스팅 환경에서는 자동 주입됩니다. 로컬에서 Application Insights로 추적을 보내려면 설정하십시오. 없으면 에이전트가 경고를 출력합니다.
`PORT`	아니오	수신 포트. 기본값 `8088`.
	.NET file-based app	uv 단일 파일 스크립트
인라인 의존성	`#:package Foo@1.2.3`	PEP 723 `# /// script` 블록
실행	`dotnet run agent.cs`	`uv run agent_msaf.py`
Linux용 publish	`dotnet publish -r linux-x64`	`uv export` + `uv pip install --target --python-platform`
압축	SDK가 폴더 경로를 받아 처리	`deploy.py`가 직접 수행. SDK는 스트림을 받음
entry point	`["dotnet", "<assembly>.dll"]`, `*.runtimeconfig.json`에서 역산	`["python", "<name>.py"]`, 모듈 가림 여부를 검사
런타임 ID	`dotnet_10`	`python_3_13`
함정	publish 기본값이 NativeAOT이므로 꺼야 함	크로스 플랫폼 휠, 그리고 스크립트 이름의 모듈 가림
증상	원인과 해결
`Failed to acquire a token`	갱신 토큰 만료. `az login --tenant <tenant-id>`를 실행하십시오. `az account show`는 이 상황에서도 성공한다는 점을 기억하십시오.
`AADSTS700016`	환경에 `AZURE_CLIENT_ID` / `AZURE_CLIENT_SECRET`이 남아 있습니다. `FOUNDRY_AUTH=cli`로 실행하거나 해당 변수를 제거하십시오.
`az`를 찾을 수 없음	`cmd /c az version`으로 확인하십시오. Windows에서 Azure CLI는 `.cmd` 심(shim)이라 로그인 셸이 아닌 환경의 `PATH`에서 빠져 있을 수 있습니다.
`No solution found when resolving script dependencies`	의존성 그래프 어딘가에 프리릴리스가 필요합니다. 에이전트 스크립트의 `[tool.uv] prerelease = "allow"` 블록이 `# ///` 울타리 안에 있고 모든 줄이 주석 처리되어 있는지 확인하십시오.
vendoring 중 `<pkg> has no usable wheels`	해당 패키지에 `TARGET_PLATFORM`용 휠이 없습니다. `deploy.py`의 `manylinux` 기준을 올리거나, 휠이 있는 버전으로 고정하거나, 의존성을 제거하십시오.
컨테이너 기동 시 `ModuleNotFoundError`	거의 항상 플랫폼 불일치입니다. 번들이 잘못된 OS나 Python 버전으로 vendoring된 것입니다. `deploy.py`의 `TARGET_PLATFORM` / `TARGET_PYTHON`은 `PYTHON_RUNTIME`과 일치해야 합니다.
`httpx`를 언급하는 `ImportError`	`openai` 3이 `httpx2`로 옮겨갔지만 `azure-ai-projects`는 여전히 `httpx`를 임포트합니다. `openai>=2.45,<3` 고정을 유지하십시오.
`shadows the standard library module`	스크립트 파일명이 실제 모듈과 충돌합니다. 이름을 바꾸십시오.
버전 생성 시 `(invalid_parameters) ValidationError`	에이전트 이름이 유효하지 않습니다. 대개 두 번째 인수로 넘긴 이름에 밑줄이 들어간 경우입니다. 하이픈을 쓰십시오(`agent_msaf`가 아니라 `agent-msaf`).
`is not a valid Foundry agent name`	같은 문제를, 업로드가 시작되기 전에 로컬에서 잡아낸 것입니다. 메시지에 올바른 형태가 제안됩니다.
`424 session_not_ready`	entry point 불일치 또는 컨테이너 기동 실패. 포털의 버전 상세를 확인하십시오.
`The agent deployed but failed on its first invocation`	버전은 Active이고 라우팅도 끝났으며, 컨테이너 자체가 실패한 것입니다. 메시지에 서버가 준 `code` / `message`가 그대로 담깁니다. `uv run <agent>.py`로 로컬에서 동일한 경로를 재현할 수 있습니다.
`401 PermissionDenied ... lacks the required data action`	에이전트의 관리 ID에 역할이 없습니다. 3. 에이전트 자신의 ID에 역할 부여를 보십시오. 프레임워크가 아니라 ID 수준의 문제이므로 두 에이전트 모두에 동일하게 해당합니다.
`does not have permissions for ... AIServices/agents/read` (경고)	같은 역할 누락의 약한 증상입니다. 대화 기록을 가져오지 못해 멀티턴 문맥이 사라지지만 단일 턴 응답은 정상입니다.
`FoundryToolRuntime is not configured`	LangGraph 전용. `from_langgraph()`에 `credentials`를 넘기지 않았거나 `AZURE_AI_PROJECT_ENDPOINT`가 비어 있습니다. `agent_lg.py`가 반드시 맞춰야 하는 세 가지를 보십시오.
`401 Incorrect API key provided: unused`	LangGraph 전용. `ChatOpenAI`가 주입한 클라이언트를 `api.openai.com`을 향하는 기본 클라이언트로 바꿔치기한 것입니다. `root_async_client`와 함께 `async_client`도 넘기십시오.
로컬 실행 시 `CERTIFICATE_VERIFY_FAILED`	사내 TLS 검사(Zscaler 등). `httpx`는 certifi를 쓰며 OS 신뢰 저장소를 보지 않습니다. certifi의 `cacert.pem`과 사내 루트 CA를 이어붙인 번들을 만들어 `SSL_CERT_FILE`로 지정하십시오. 호스팅 컨테이너에는 해당하지 않습니다.
호스팅에서는 되는데 로컬에서 `AADSTS700016`	셸에 `AZURE_CLIENT_ID` / `AZURE_TENANT_ID` / `AZURE_CLIENT_SECRET`이 남아 있습니다. `DefaultAzureCredential`이 `az login`보다 그 서비스 주체를 먼저 시도합니다. 로컬 실행 시에는 제거하십시오.
`Cannot create item resource helper` / `OutputTextEventGenerator did not process message` (경고)	LangGraph 전용이며 표시상의 문제입니다. LangChain이 내용이 빈 `AIMessageChunk`(맨 앞 청크와 `finish_reason`만 담은 마지막 청크)를 내보내는데, 어댑터의 이벤트 생성기에 내용이 없는 청크를 처리하는 분기가 없어 로그만 남기고 건너뜁니다. 텍스트를 담은 청크는 모두 정상 변환되며, 스트림은 완전한 `output_text.done`과 `response.completed`로 끝납니다.
`Conversation with ID conv_... not found` (경고, 404)	대화의 첫 턴에서는 정상입니다. 가져올 기록이 아직 없을 뿐이고 어댑터는 `No historical items found`로 계속 진행합니다. 같은 경고의 403 형태와는 다르며, 403은 역할 할당 누락을 뜻합니다.
`missing a PEP 723 '# /// script' metadata block` 경고	에이전트에 인라인 의존성 메타데이터가 없어, 함께 번들될 패키지가 하나도 없습니다.
에이전트가 `PORT`를 무시함	LangGraph 호스트만 그렇습니다(`DEFAULT_AD_PORT`를 읽습니다). `agent_lg.py`는 이미 `PORT`를 명시적으로 전달하므로, 마지막 줄을 수정하더라도 그 인수는 유지하십시오.
버전이 `Active`로 전이하지 않음	10분 데드라인 후 `TimeoutError`. 포털에서 버전의 `error` 객체를 확인하십시오.
`Provisioning failed`	포털의 버전 상세 페이지를 여십시오. 거기 있는 `error.code` / `error.message`가 실제 진단입니다.
File	Role
`agent_msaf.py`	The agent, on the Microsoft Agent Framework.
`agent_lg.py`	The same agent, on LangGraph.
`deploy.py`	A local deployment script: publish → create version → wait for active → route the endpoint → smoke test. Takes either agent as its argument.
`.env.example`	Template for running an agent locally. Copy to `.env`.