From 9a6d2a4a5db6a4dbdd21c194a568da451a480fec Mon Sep 17 00:00:00 2001 From: Nikhil Pareek Date: Fri, 16 Oct 2026 18:00:17 -0700 Subject: [PATCH] docs(integrations): Semantic Kernel (Python) tracing (TH-8241) Co-Authored-By: Claude Sonnet 5.5 --- .../integrations/traceai/semantic-kernel.mdx | 106 ++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 src/pages/docs/integrations/traceai/semantic-kernel.mdx diff --git a/src/pages/docs/integrations/traceai/semantic-kernel.mdx b/src/pages/docs/integrations/traceai/semantic-kernel.mdx new file mode 100644 index 000000000..aaf325e45 --- /dev/null +++ b/src/pages/docs/integrations/traceai/semantic-kernel.mdx @@ -0,0 +1,106 @@ +--- +title: "Semantic Kernel (Python) Tracing with Future AGI" +description: "Trace Semantic Kernel for Python agents, tool calls and model calls in Future AGI with traceAI-semantic-kernel, built on Semantic Kernel's own OpenTelemetry diagnostics." +--- + +`traceAI-semantic-kernel` turns on Semantic Kernel's built-in OpenTelemetry GenAI diagnostics and maps its spans to Future AGI span kinds. It does not wrap `Kernel.invoke` or any connector. Semantic Kernel creates every span you see. + + +Alpha. Semantic Kernel marks these diagnostics experimental, so span names and keys can change in a later release. This page is for Semantic Kernel **for Python**. It is not the [Java package](/docs/integrations/traceai/java/frameworks), not .NET Semantic Kernel, and not Microsoft Agent Framework. + + +## Install + +```bash +pip install traceAI-semantic-kernel semantic-kernel +``` + +Requires Python 3.10 to 3.13 and `semantic-kernel>=1.38.0,<2`. Semantic Kernel pulls in a pre-release dependency (`azure-ai-agents`), so with `uv` add `--prerelease=allow`. + +## Configure + +```bash +export FI_API_KEY="YOUR_API_KEY" +export FI_SECRET_KEY="YOUR_SECRET_KEY" +``` + +```python +from fi_instrumentation import register, using_session +from fi_instrumentation.fi_types import ProjectType +from traceai_semantic_kernel import SemanticKernelInstrumentor + +trace_provider = register(project_type=ProjectType.OBSERVE, project_name="my-sk-app") + +# Turns on Semantic Kernel's diagnostics in process. You do not set any SEMANTICKERNEL_* variable. +SemanticKernelInstrumentor().instrument(tracer_provider=trace_provider) + +# Build your Kernel / ChatCompletionAgent as usual. +with using_session("conversation-123"): # Semantic Kernel emits no thread id + response = await agent.get_response("What is the weather in Paris?") + +trace_provider.force_flush() # short scripts: the batch exporter sends in the background +``` + +Call `instrument()` once, after any `add_span_processor()` of your own. It is idempotent. `uninstrument()` restores Semantic Kernel. + +## What is captured + +``` +invoke_agent WeatherAgent AGENT +└─ AutoFunctionInvocationLoop CHAIN + ├─ chat gpt-6-luna LLM model, input and output tokens + ├─ execute_tool Weather-get_weather TOOL + └─ chat gpt-6-luna LLM +``` + +| In Future AGI | Source | +|---|---| +| Span kind (`LLM`, `TOOL`, `AGENT`, `CHAIN`) | Set by traceAI from Semantic Kernel's operation names. A function you call yourself (`kernel.invoke`, `kernel.invoke_prompt`) is `CHAIN`; a function the model asked for is `TOOL` | +| Model, provider | `gen_ai.request.model`; provider copied from `gen_ai.system` | +| Input and output tokens | On `chat` spans, as Semantic Kernel reports them; streaming included | +| Errors | ERROR status and `error.type` on failed model, agent and tool calls | +| Session | `session.id` from `using_session` / `using_attributes`; Semantic Kernel supplies none | + +Not captured: retrieval spans (memory and vector connectors), cost, cache and reasoning token counts. The Azure AI Inference connector reads its own diagnostics settings and is not switched on by `instrument()`. + +## Privacy + +Default is `sensitive=False`: no prompt, completion, agent message, tool argument or tool result is exported. Tool names, tool definitions (the function schema you registered), model names, token counts and ids are exported. Exception stack traces (which hold local file paths) are always removed, and with `sensitive=False` the exception message is removed too: a failed tool shows as `ERROR` with the status text `RuntimeError`, not the message. + +To store content, opt in: + +```python +SemanticKernelInstrumentor().instrument(tracer_provider=trace_provider, sensitive=True) +``` + +`sensitive=True` stores prompts, completions, agent messages, tool arguments and results, and exception messages. `FI_HIDE_INPUTS=true` and `FI_HIDE_OUTPUTS=true` (or `TraceConfig(hide_inputs=True, ...)`) still drop the input or output side. With `sensitive=False`, `instrument()` also overrides a sensitive flag set in your environment or `.env`, and logs a warning. + +## Tested versions + +| `semantic-kernel` | Python | Result | +|---|---|---| +| 1.45.0 (latest stable, 2026-10-16) | 3.12 | 63 tests; live run against a local Future AGI | +| 1.44.1 | 3.10 to 3.13, 3.12 live run | pass | +| 1.38.0 (floor) | 3.10 to 3.13 | pass | + +Before 1.38.0 the operation string and agent keys differ (`chat.completions`, `gen_ai.agent.invocation_input`), so it is not supported. + +## Troubleshooting + +- **No spans arrive.** Check that `instrument()` received the provider returned by `register()`. A provider that is not an OpenTelemetry SDK `TracerProvider` is skipped with a WARNING. +- **Spans arrive without kinds.** You called `add_span_processor()` after `instrument()`. Call `uninstrument()` then `instrument()` again. +- **Token counts are doubled.** You also enabled a client instrumentor (`traceAI-openai`, `traceAI-litellm`, and so on). Use one or the other. +- **Chat spans have no prompt text with `sensitive=True`.** Semantic Kernel writes model-call messages to Python logging at INFO. Keep logging from raising the logger level above INFO for the Semantic Kernel module. +- **Short script exits before export.** Call `trace_provider.force_flush()`. + +## Limitations + +- Experimental upstream diagnostics; a Semantic Kernel upgrade can change span names. +- A function called by your own auto-function-invocation filter, or inside a streaming consumer, can show as `TOOL` instead of `CHAIN` (kind only). +- Semantic Kernel sets no conversation id, so sessions need `using_session`. + +## How this differs from related integrations + +- **Microsoft Agent Framework** is a different SDK with its own integration; do not use this package for it. +- **traceAI-openai / traceAI-litellm** instrument the client call. Use them for plain client code; do not combine them with this package for the same calls. +- **Java Semantic Kernel** (`traceai-java-semantic-kernel`) is a separate package and is unchanged.