castia 0.1.0__tar.gz

castia-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Byte-compiled / optimized / cache
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+*.egg
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.pytype/
+
+# Environment / secrets
+.env
+.env.*
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store

castia-0.1.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+# Changelog
+
+## 0.1.0 (2026-09-09)
+
+
+### Continuous Integration
+
+* automate per-language releases with release-please + PyPI Trusted Publishing ([#3](https://github.com/sethjuarez/castia/issues/3)) ([cb9db23](https://github.com/sethjuarez/castia/commit/cb9db23c1dda6ad270d51339f5adde829925c045))

castia-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Seth Juarez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

castia-0.1.0/PKG-INFO

@@ -0,0 +1,198 @@
+Metadata-Version: 2.5
+Name: castia
+Version: 0.1.0
+Summary: Idiomatic, FastAPI-style Python SDK for Microsoft Foundry hosted agents.
+Project-URL: Homepage, https://github.com/sethjuarez/castia
+Project-URL: Repository, https://github.com/sethjuarez/castia
+Project-URL: Documentation, https://castia.dev
+Author: Seth Juarez
+License-Expression: MIT
+License-File: LICENSE
+Keywords: activity,adaptive-cards,agents,fastapi,foundry,microsoft-foundry,sdk,teams
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: azure-ai-projects>=2.3.0
+Requires-Dist: azure-identity>=1.19
+Requires-Dist: fastapi>=0.115
+Requires-Dist: httpx<1,>=0.28.1
+Requires-Dist: microsoft-opentelemetry>=1.3.8
+Requires-Dist: pyjwt>=2.9
+Requires-Dist: uvicorn[standard]>=0.30
+Provides-Extra: deploy
+Requires-Dist: ruamel-yaml>=0.18; extra == 'deploy'
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == 'test'
+Requires-Dist: ruamel-yaml>=0.18; extra == 'test'
+Description-Content-Type: text/markdown
+
+# castia
+
+Idiomatic, FastAPI-style Python SDK for [Microsoft Foundry](https://ai.azure.com)
+hosted agents.
+
+`castia` lets a hosted agent speak Foundry's three wire protocols — Activity
+(Teams/Bot Framework), OpenAI `responses`, and `invocations` — through
+protocol-named decorators, dependency injection (`Depends`), and typed builders
+for messages, Adaptive Cards, entities, and invoke envelopes. You decorate a
+handler, return a value, and the framework does the rest — the auth chains,
+hosting, Activity routing, and telemetry stay out of your file.
+
+## Install
+
+```bash
+pip install castia
+# or, with uv:
+uv add castia
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+```python
+from castia import Agent, Depends, Model, Teams
+
+app = Agent(name="my-agent")
+
+def gpt4o() -> Model:
+    return Model("gpt-4o")
+
+@app.message(Teams.direct, Teams.group, Teams.channel_mention)
+async def reply(text: str, model: Model = Depends(gpt4o)) -> str:
+    return await model.respond(text)
+
+if __name__ == "__main__":
+    app.run()
+```
+
+Decorate a handler with the surfaces it answers on, return a `str`, and the
+framework sends it as the Teams reply. The model is built **once** for the
+process and injected via `Depends` — the model choice stays visible in your file
+instead of being buried in the framework. (`Model()` with no argument falls back
+to `AZURE_AI_MODEL_DEPLOYMENT_NAME`; `get_model` / `use_model("gpt-4o")` are
+zero-config conveniences.)
+
+### Composing protocols with routers
+
+Like FastAPI's `include_router`, an `Agent` composes `Router`s so each protocol
+can live in its own module:
+
+```python
+from castia import Agent
+from handlers import activity, responses, invocations
+
+app = Agent(name="my-agent")
+app.include(activity.router, responses.router, invocations.router)
+```
+
+### Richer replies
+
+Handlers can take a `Message` and reach for typed builders — Adaptive Cards,
+suggested actions, citations, mentions, sensitivity labels, live-typing
+streamers, and reactions:
+
+```python
+from castia import Depends, Message, Model, Reaction, Router, Teams
+
+router = Router()
+
+@router.activity(Teams.direct)
+async def reply(text: str, msg: Message, model: Model = Depends(get_model)) -> None:
+    await msg.react(Reaction.eyes)
+    answer = await model.respond(text)
+    await msg.say(answer)
+```
+
+## Protocols
+
+`castia` publishes handlers for the protocols in `PUBLISHABLE_PROTOCOLS`:
+
+- **Activity** — Teams / Bot Framework message and invoke turns.
+- **`responses`** — the OpenAI `responses` wire shape.
+- **`invocations`** — Foundry invoke envelopes (tool execution, agent-to-agent).
+
+## Observability & evaluation
+
+`castia` configures Foundry/Agent 365 telemetry for you when the agent starts.
+By default it emits GenAI spans (the `chat {model}` spans the Foundry Traces UI
+keys off) but does **not** record the prompt/response **content** onto them.
+
+Recording content is what makes an agent's traces *evaluable* — trace-based
+evaluators read the input/output text from the GenAI spans, which is only present
+when content recording is enabled. Turn it on deliberately via
+`configure_observability`:
+
+```python
+from castia.observability import configure_observability
+
+# Records prompt/response text onto GenAI spans so traces can be evaluated.
+configure_observability(enable_content_recording=True)
+```
+
+Resolution order for each flag is **explicit argument > environment variable >
+default**:
+
+| Flag | Argument | Environment variable | Default |
+| --- | --- | --- | --- |
+| Content recording | `enable_content_recording` | `AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED` | off |
+| GenAI tracing | `enable_genai_tracing` | `AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING` | on |
+
+Passing nothing preserves the default behavior. Telemetry setup is best-effort:
+a failure is logged, never raised, so it can't break startup or a turn.
+
+> **Security caveat:** enabling content recording writes prompt and response
+> **text** to Application Insights. Only enable it where storing that content is
+> acceptable for your data-handling and privacy requirements.
+
+### Building a scored eval suite
+
+Once your traces are evaluable, `python -m castia eval` wraps the
+`azd ai agent eval` extension to synthesize and run a **scored** eval suite — a
+generated JSONL dataset plus an auto-generated, weighted **rubric** (a custom
+multi-dimension evaluator):
+
+```bash
+# Offline gate — validate eval.yaml + rubric files, no Azure, free in CI:
+python -m castia eval check
+
+# Synthesize a rubric + dataset from the agent instruction (billable):
+python -m castia eval generate --agent my-agent --max-samples 25
+
+# Re-upload locally edited rubric/dataset files as a new version:
+python -m castia eval update --evaluator-only
+
+# Submit a scored run against the deployed agent (billable):
+python -m castia eval run
+```
+
+`check` is a pure, offline referential-integrity gate: it resolves every
+evaluator/dataset `local_uri` and validates each rubric dimensions file.
+`generate` and `run` submit **billable** Foundry jobs, so both accept
+`--dry-run` to print the resolved `azd` command line without submitting
+anything. The `azd` wrappers need the build-time extra: `pip install
+'castia[deploy]'`.
+
+The rubric dimensions file is a **bare JSON list** where each entry is keyed by
+`id` (a stable slug like `correct_outcome`), with an optional
+`always_applicable: true` on the catch-all dimension. That cross-SDK shape is
+pinned in the monorepo at [`spec/conformance/rubric/`](../../spec/conformance/rubric).
+
+## Design
+
+`castia` is deliberately import-cheap: `import castia` never pulls in the
+instrumented Azure/OpenAI/httpx stacks, so telemetry can be configured before
+those libraries load. The heavy imports are deferred into the methods that need
+them.
+
+## License
+
+MIT © 2026 Seth Juarez

castia-0.1.0/README.md

@@ -0,0 +1,162 @@
+# castia
+
+Idiomatic, FastAPI-style Python SDK for [Microsoft Foundry](https://ai.azure.com)
+hosted agents.
+
+`castia` lets a hosted agent speak Foundry's three wire protocols — Activity
+(Teams/Bot Framework), OpenAI `responses`, and `invocations` — through
+protocol-named decorators, dependency injection (`Depends`), and typed builders
+for messages, Adaptive Cards, entities, and invoke envelopes. You decorate a
+handler, return a value, and the framework does the rest — the auth chains,
+hosting, Activity routing, and telemetry stay out of your file.
+
+## Install
+
+```bash
+pip install castia
+# or, with uv:
+uv add castia
+```
+
+Requires Python 3.11+.
+
+## Quickstart
+
+```python
+from castia import Agent, Depends, Model, Teams
+
+app = Agent(name="my-agent")
+
+def gpt4o() -> Model:
+    return Model("gpt-4o")
+
+@app.message(Teams.direct, Teams.group, Teams.channel_mention)
+async def reply(text: str, model: Model = Depends(gpt4o)) -> str:
+    return await model.respond(text)
+
+if __name__ == "__main__":
+    app.run()
+```
+
+Decorate a handler with the surfaces it answers on, return a `str`, and the
+framework sends it as the Teams reply. The model is built **once** for the
+process and injected via `Depends` — the model choice stays visible in your file
+instead of being buried in the framework. (`Model()` with no argument falls back
+to `AZURE_AI_MODEL_DEPLOYMENT_NAME`; `get_model` / `use_model("gpt-4o")` are
+zero-config conveniences.)
+
+### Composing protocols with routers
+
+Like FastAPI's `include_router`, an `Agent` composes `Router`s so each protocol
+can live in its own module:
+
+```python
+from castia import Agent
+from handlers import activity, responses, invocations
+
+app = Agent(name="my-agent")
+app.include(activity.router, responses.router, invocations.router)
+```
+
+### Richer replies
+
+Handlers can take a `Message` and reach for typed builders — Adaptive Cards,
+suggested actions, citations, mentions, sensitivity labels, live-typing
+streamers, and reactions:
+
+```python
+from castia import Depends, Message, Model, Reaction, Router, Teams
+
+router = Router()
+
+@router.activity(Teams.direct)
+async def reply(text: str, msg: Message, model: Model = Depends(get_model)) -> None:
+    await msg.react(Reaction.eyes)
+    answer = await model.respond(text)
+    await msg.say(answer)
+```
+
+## Protocols
+
+`castia` publishes handlers for the protocols in `PUBLISHABLE_PROTOCOLS`:
+
+- **Activity** — Teams / Bot Framework message and invoke turns.
+- **`responses`** — the OpenAI `responses` wire shape.
+- **`invocations`** — Foundry invoke envelopes (tool execution, agent-to-agent).
+
+## Observability & evaluation
+
+`castia` configures Foundry/Agent 365 telemetry for you when the agent starts.
+By default it emits GenAI spans (the `chat {model}` spans the Foundry Traces UI
+keys off) but does **not** record the prompt/response **content** onto them.
+
+Recording content is what makes an agent's traces *evaluable* — trace-based
+evaluators read the input/output text from the GenAI spans, which is only present
+when content recording is enabled. Turn it on deliberately via
+`configure_observability`:
+
+```python
+from castia.observability import configure_observability
+
+# Records prompt/response text onto GenAI spans so traces can be evaluated.
+configure_observability(enable_content_recording=True)
+```
+
+Resolution order for each flag is **explicit argument > environment variable >
+default**:
+
+| Flag | Argument | Environment variable | Default |
+| --- | --- | --- | --- |
+| Content recording | `enable_content_recording` | `AZURE_TRACING_GEN_AI_CONTENT_RECORDING_ENABLED` | off |
+| GenAI tracing | `enable_genai_tracing` | `AZURE_EXPERIMENTAL_ENABLE_GENAI_TRACING` | on |
+
+Passing nothing preserves the default behavior. Telemetry setup is best-effort:
+a failure is logged, never raised, so it can't break startup or a turn.
+
+> **Security caveat:** enabling content recording writes prompt and response
+> **text** to Application Insights. Only enable it where storing that content is
+> acceptable for your data-handling and privacy requirements.
+
+### Building a scored eval suite
+
+Once your traces are evaluable, `python -m castia eval` wraps the
+`azd ai agent eval` extension to synthesize and run a **scored** eval suite — a
+generated JSONL dataset plus an auto-generated, weighted **rubric** (a custom
+multi-dimension evaluator):
+
+```bash
+# Offline gate — validate eval.yaml + rubric files, no Azure, free in CI:
+python -m castia eval check
+
+# Synthesize a rubric + dataset from the agent instruction (billable):
+python -m castia eval generate --agent my-agent --max-samples 25
+
+# Re-upload locally edited rubric/dataset files as a new version:
+python -m castia eval update --evaluator-only
+
+# Submit a scored run against the deployed agent (billable):
+python -m castia eval run
+```
+
+`check` is a pure, offline referential-integrity gate: it resolves every
+evaluator/dataset `local_uri` and validates each rubric dimensions file.
+`generate` and `run` submit **billable** Foundry jobs, so both accept
+`--dry-run` to print the resolved `azd` command line without submitting
+anything. The `azd` wrappers need the build-time extra: `pip install
+'castia[deploy]'`.
+
+The rubric dimensions file is a **bare JSON list** where each entry is keyed by
+`id` (a stable slug like `correct_outcome`), with an optional
+`always_applicable: true` on the catch-all dimension. That cross-SDK shape is
+pinned in the monorepo at [`spec/conformance/rubric/`](../../spec/conformance/rubric).
+
+## Design
+
+`castia` is deliberately import-cheap: `import castia` never pulls in the
+instrumented Azure/OpenAI/httpx stacks, so telemetry can be configured before
+those libraries load. The heavy imports are deferred into the methods that need
+them.
+
+## License
+
+MIT © 2026 Seth Juarez

castia-0.1.0/RELEASING.md

@@ -0,0 +1,65 @@
+# Releasing `castia` (Python)
+
+Releases are automated by [release-please](https://github.com/googleapis/release-please)
+and published to PyPI with **Trusted Publishing** (OIDC) — no API token is stored
+in the repository. You should never build or upload from a laptop.
+
+## One-time PyPI setup (before the first publish)
+
+`castia` is not on PyPI yet, so register a **pending** trusted publisher:
+
+1. Go to <https://pypi.org/manage/account/publishing/>.
+2. Add a new pending publisher with exactly:
+   - **PyPI project name:** `castia`
+   - **Owner:** `sethjuarez`
+   - **Repository name:** `castia`
+   - **Workflow name:** `release-please.yml`
+   - **Environment name:** `pypi`
+3. (Recommended) In the GitHub repo, create a **`pypi` environment**
+   (Settings → Environments) and add required reviewers so a human approves each
+   publish.
+
+After the first successful publish, the pending publisher becomes a normal
+trusted publisher automatically.
+
+## The steady-state flow
+
+1. Merge Conventional-Commit PRs into `main` (see [`CONTRIBUTING.md`](../../CONTRIBUTING.md)).
+2. release-please maintains an open **release PR** titled like
+   `chore(main): release python 0.2.0`. It bumps `pyproject.toml`'s version and
+   updates `CHANGELOG.md`.
+3. **Merging that release PR** creates the tag `python-v<version>` and a GitHub
+   release, then the `release-please` workflow's `publish-python` job builds the
+   wheel + sdist and uploads them to PyPI.
+
+You do not push tags by hand; merging the release PR is the release action.
+
+## First release (0.1.0) bootstrap
+
+`.release-please-manifest.json` starts the `packages/python` component at
+`0.0.0`. The commit that introduces release-please carries a
+`Release-As: 0.1.0` footer, which makes release-please open its first release PR
+at **0.1.0** (matching the version already in `pyproject.toml`) regardless of the
+commit types before it. Merging that first release PR publishes `castia 0.1.0`.
+
+No sticky configuration is left behind: after 0.1.0 ships, the manifest advances
+to `0.1.0` and subsequent versions are derived normally from Conventional
+Commits.
+
+## Versioning scheme
+
+- Per-language tags: the Python SDK releases as `python-v<version>` (e.g.
+  `python-v0.1.0`). A future Rust SDK would release independently as
+  `rust-v<version>`.
+- Pre-1.0: `feat` → minor, `fix` → patch, breaking changes are **not**
+  auto-promoted to a major (`bump-minor-pre-major`).
+
+## Verifying a release build locally (optional)
+
+You never publish locally, but you can reproduce what CI builds:
+
+```bash
+cd packages/python
+uv build
+uvx twine check dist/*
+```

castia-0.1.0/pyproject.toml

@@ -0,0 +1,72 @@
+[project]
+name = "castia"
+version = "0.1.0"
+description = "Idiomatic, FastAPI-style Python SDK for Microsoft Foundry hosted agents."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+authors = [{ name = "Seth Juarez" }]
+keywords = [
+    "foundry",
+    "microsoft-foundry",
+    "agents",
+    "teams",
+    "fastapi",
+    "sdk",
+    "activity",
+    "adaptive-cards",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Typing :: Typed",
+]
+dependencies = [
+    "fastapi>=0.115",
+    "uvicorn[standard]>=0.30",
+    "httpx>=0.28.1,<1",
+    "pyjwt>=2.9",
+    "azure-ai-projects>=2.3.0",
+    "azure-identity>=1.19",
+    "microsoft-opentelemetry>=1.3.8",
+]
+
+[project.urls]
+Homepage = "https://github.com/sethjuarez/castia"
+Repository = "https://github.com/sethjuarez/castia"
+Documentation = "https://castia.dev"
+
+[project.optional-dependencies]
+# Build-time only: used by `python -m castia deploy` to rewrite azure.yaml from
+# the decorators. Deliberately not a runtime dependency so it never ships in the
+# hosted container.
+deploy = ["ruamel.yaml>=0.18"]
+# Test-time only. Includes ruamel.yaml because the eval-suite tests parse real
+# eval.yaml / rubric fixtures.
+test = ["pytest>=8", "ruamel.yaml>=0.18"]
+
+[tool.uv]
+prerelease = "allow"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/castia"]
+
+[tool.ruff.lint.flake8-bugbear]
+# `Depends(...)` is an inert marker -- like FastAPI's, it never calls the
+# provider, it just records it -- so calling it in an argument default is safe.
+# This silences B008 without a `# noqa` on the handler.
+extend-immutable-calls = ["castia.Depends"]

castia-0.1.0/src/castia/TRACING.md

@@ -0,0 +1,115 @@
+# Trace labels in the Foundry Traces UI
+
+A working reference for the span badges in the trace tree — **In Process**,
+**HTTP**, **Invoke Agent**, **Chat** — and a warning about one badge that lies.
+Written after a bug bash where we watched the framework/HTTP badges flip on their
+own and spent a long time blaming our own code before finding the real cause: a
+non-deterministic query in the Foundry Traces portal.
+
+## Where the labels come from
+
+Two different things feed the badges, and only one of them is under our control.
+
+**1. Our own operation spans — stable, ours to set.** The spans we create in
+`tracing.py` (`invoke_agent`, `execute_tool`) carry `gen_ai.operation.name`, a
+fixed vocabulary the portal recognises: `invoke_agent` → Invoke Agent, `chat` →
+Chat, `execute_tool` → Execute Tool. We set these explicitly, at span creation,
+on spans we own. They render correctly and do not flicker.
+
+**2. Framework and client span "kind" — computed at export.** For every other
+span (the SDK's `agents.adapter.process`, the auth/MSI HTTP calls, …) the badge
+derives from the Azure-Monitor *dependency type* the exporter writes into App
+Insights. That logic lives in
+`azure/monitor/opentelemetry/exporter/export/trace/_exporter.py`:
+
+| Span shape | Exported type | Badge |
+| --- | --- | --- |
+| `SpanKind.INTERNAL`, no mapping attributes | `InProc` | **In Process** |
+| `SpanKind.INTERNAL` **with** `gen_ai.system` | `gen_ai.*` | (GenAI type) |
+| `SpanKind.CLIENT` + `http.method` / `http.request.method` | `HTTP` | **HTTP** (renders the verb) |
+| `SpanKind.CLIENT` + `db.system` / messaging / rpc | that system | (its own type) |
+| `SpanKind.SERVER` / `CONSUMER` | — | a Request, not a dependency |
+| `SpanKind.CLIENT` with none of the recognised attributes | *(blank)* | **Other** |
+
+This exported `type` is written once, is single-valued, and is immutable in App
+Insights. `az monitor app-insights query` returns the correct `HTTP` / `InProc`
+for these spans every time, hours or days later.
+
+## The one rule: stamp identity, restyle nothing
+
+`_AgentIdentitySpanProcessor.on_start` (in `observability.py`) runs on **every**
+span on the provider. Its only job is to stamp the agent-identity attributes the
+Foundry portal needs to associate the run with the agent:
+
+- `gen_ai.agent.name`, `gen_ai.agent.version`, `gen_ai.agent.id`
+- `microsoft.foundry.project.id`, `gen_ai.azure_ai_project.id`
+
+Those keys are neutral — none is a mapping attribute the exporter keys off, so
+they do not change any span's exported `type`. Keep it that way. **Do not** stamp
+classification-affecting attributes (`gen_ai.operation.name`, `gen_ai.system`,
+`http.*`) onto framework or client spans from a blanket processor; set operation
+names only on spans we own, at creation, in `tracing.py`.
+
+This rule is about keeping the underlying App Insights `type` clean. It is good
+hygiene, but note it is **not** what makes the framework badge flicker — see next.
+
+## The badge that lies: portal query is non-deterministic
+
+**Symptom.** In the Traces UI, the **kind** badge on framework and HTTP spans
+(e.g. `agents.adapter.process`, `GET /msi/token`) randomly flips to
+**default / Other** on runs that are already complete and stored. No redeploy, no
+new run, no data change — just refreshing or reopening the same trace is enough to
+change it. It flips back on a later read. Seen across agent versions (confirmed on
+v13 op `6efde7c97049e6214d5aee83d1fc4305` and a v18 run `ad28e31a…`).
+
+**Root cause — portal-side, not our telemetry.** The Traces detail query
+`spanAppInsightsLLMCallBaseQueryOpt` (fired when a run is opened) builds two
+projections of the *same* spans and unions them:
+
+- `normal_spans`: `span_type = type` — the real exported type (`HTTP` / `InProc`)
+- `gen_ai_spans`: `span_type = "default"` — a hardcoded literal, applied to
+  **every** span with **no filter**
+
+Then it collapses per span id with a non-deterministic aggregate:
+
+```kusto
+gen_ai_spans
+| ...
+| union normal_spans
+| summarize spanType = any(span_type), ...
+  by id, operationId = operation_Id, operationParentId = operation_ParentId
+```
+
+Each span id now has two rows with conflicting `span_type` — its real type and
+`"default"` — and `any()` in KQL is explicitly non-deterministic. Every execution
+arbitrarily returns one or the other, so the badge is a coin-flip on each read.
+
+**Why it looked like "decay" or a per-version difference.** Nothing decayed and
+nothing was version-specific. A span that "stayed correct for hours" was just
+winning the `any()` toss on the reads we happened to look at; a span that "flipped
+on its own" lost one. The captured detail query is byte-for-byte identical across
+v13 and v18 except the `operation_Id` and version filter.
+
+**None of our code is involved.** Our agent emits correct spans; App Insights
+stores the correct `type` immutably. The flip is entirely in the portal's derived
+query. Reported to the Foundry team; suggested fix is to filter `gen_ai_spans` to
+spans with `gen_ai.operation.name` set (so a span contributes one `span_type`), or
+to replace `any(span_type)` with a deterministic pick (`arg_max` / `coalesce` /
+`max`) that prefers the real type.
+
+## How to verify (ground truth)
+
+Do **not** trust the UI badge for framework/HTTP spans — query App Insights
+directly, where the type is immutable and correct:
+
+```kusto
+dependencies
+| where operation_Id == "<your-operation-id>"
+| project id, name, type, timestamp
+```
+
+- A framework span (e.g. `agents.adapter.process`) shows `type == "InProc"`.
+- An auth/MSI call (e.g. `GET /msi/token`) shows `type == "HTTP"`.
+
+If those rows are correct but the UI badge reads **Other**, it is the portal
+`any()` query, not the runtime and not our processor.