Bug: Missing System Prompt In Microsoft Agent Framework Trace

Introduction

This article addresses a bug encountered while using the Microsoft Agent Framework with Langfuse, where the system prompt is not displayed in the trace. This issue affects the visibility of the instructions given to the agent, making it harder to debug and understand the agent's behavior. We will explore the details of the bug, the steps to reproduce it, and the environment in which it was found. This detailed analysis aims to provide a comprehensive understanding of the problem and potential solutions.

Describe the Bug

The core issue is that when using the Microsoft Agent Framework with Langfuse for tracing, the system prompt provided to the agent is not visible in the Langfuse trace. The system prompt serves as the initial instructions or context for the agent, and its absence from the trace makes it difficult to fully understand the agent's decision-making process. This lack of visibility can complicate debugging and optimization efforts, as the trace should ideally provide a complete picture of the agent's operation, including the system prompt.

The absence of the system prompt in the trace means that developers and users cannot easily see the initial instructions that guided the agent's responses. This is a significant problem because the system prompt is crucial for setting the tone, context, and constraints for the agent's behavior. Without this information, it becomes challenging to assess whether the agent is functioning as intended and to identify the root causes of any unexpected behavior or errors. Therefore, ensuring that the system prompt is correctly displayed in the trace is essential for effective monitoring and management of agents within the Microsoft Agent Framework.

Steps to Reproduce

To reproduce this bug, follow these steps:

1. Set up the Environment: Ensure you have Python 3.9 or higher installed, along with the necessary libraries such as agent_framework, langfuse, and openai. You will also need an OpenRouter API key for accessing the OpenAI models.
2. Install Dependencies: Install the required Python packages using pip install agent_framework langfuse openai.
3. Configure Environment Variables: Set the OPENROUTER_API_KEY environment variable with your OpenRouter API key.
4. Run the Code: Execute the provided Python script. The script initializes a chat agent with a specific system prompt and sends a test message to it.
5. Observe the Trace: Check the Langfuse Cloud interface for the trace of the agent's execution. The bug is that the system prompt set for the agent is not displayed in the trace details.

Here is the Python code snippet used to reproduce the bug:

import asyncio
import os

from agent_framework import ChatAgent
from agent_framework.observability import setup_observability
from agent_framework.openai import OpenAIChatClient
from langfuse import get_client, observe

langfuse = get_client()
setup_observability(enable_sensitive_data=True)

gpt_5_nano_client = OpenAIChatClient(
    model_id="openai/gpt-5-nano",
    api_key=os.environ.get("OPENROUTER_API_KEY"),
    base_url="https://openrouter.ai/api/v1",
)


@observe
async def test_system_prompt():
    async with ChatAgent(
        chat_client=gpt_5_nano_client,
        instructions="Test system prompt",
    ) as agent:
        response = await agent.run("Reply an `X`")
    print(response.text)


if __name__ == "__main__":
    assert langfuse.auth_check()
    asyncio.run(test_system_prompt())

When you run this code, the agent should respond with an "X", but the trace in Langfuse Cloud will not display the "Test system prompt" instruction. This confirms the presence of the bug.

Environment Details

The bug was observed under the following environment conditions:

• Langfuse: Langfuse Cloud
• SDK Versions:
  • agent_framework: 1.0.0b251120
  • langfuse: 3.10.1
• Python Version: 3.13.9
• Operating System: Not specified in the original bug report, but this could be relevant for further investigation

These details are crucial for understanding the context in which the bug occurs. Different versions of the SDKs and Python might behave differently, and the operating system could also play a role. Ensuring that the development and testing environments match the reported environment helps in accurately reproducing and addressing the bug.

Additional Information

Langfuse Cloud or Self-Hosted?

This bug was reported on Langfuse Cloud. This distinction is important because cloud environments might have different configurations and behaviors compared to self-hosted instances. Bugs that occur in the cloud environment might be related to specific cloud configurations or services, which need to be considered during debugging.

Are you interested in contributing a fix for this bug?

The reporter indicated an interest in contributing a fix for this bug. This is valuable information as it suggests that there is a motivated individual who can potentially help resolve the issue. Collaboration between the reporter and the Langfuse team can lead to a quicker and more effective resolution.

Analyzing the Root Cause

To effectively address this bug, it's crucial to delve into the potential root causes. Several factors might be contributing to the missing system prompt in the trace. Here are some areas to investigate:

1. Observability Setup: The setup_observability function in the agent_framework might not be correctly capturing the system prompt. Reviewing the implementation of this function is essential to ensure it properly instruments the agent's execution and captures all relevant information.
2. Langfuse Integration: The integration between agent_framework and Langfuse might have issues in transmitting the system prompt. The @observe decorator and the Langfuse client's methods used within the agent framework need to be examined to verify that they correctly handle and send the system prompt data.
3. Data Serialization: There could be a problem with how the system prompt is serialized or formatted before being sent to Langfuse. If the prompt is not correctly serialized, it might be lost or ignored during transmission.
4. Langfuse Cloud Processing: The Langfuse Cloud backend might have a processing issue that prevents the system prompt from being displayed in the trace. This could be related to how the trace data is stored, indexed, or queried for display.
5. Asynchronous Context: The asynchronous nature of the code might be affecting how the system prompt is captured. If the context is not correctly propagated across asynchronous calls, the prompt might be lost within the asynchronous execution flow.

Investigating these potential causes involves debugging the code, examining the network traffic between the agent framework and Langfuse Cloud, and reviewing the Langfuse Cloud logs. A systematic approach to these investigations will help narrow down the exact cause of the bug.

Proposed Solutions and Workarounds

Based on the potential root causes, here are some proposed solutions and workarounds to address the bug:

1. Enhance Observability Setup: Modify the setup_observability function to ensure it correctly captures and propagates the system prompt. This might involve adding specific instrumentation to the ChatAgent class or adjusting how the agent's internal state is observed.
2. Review Langfuse Integration: Examine the @observe decorator and the Langfuse client calls to ensure they correctly handle the system prompt. This might involve adding custom logic to extract the system prompt and include it in the trace data.
3. Improve Data Serialization: Implement proper serialization of the system prompt to ensure it is correctly transmitted to Langfuse. This might involve using a specific serialization format (e.g., JSON) and ensuring that the prompt is properly encoded.
4. Investigate Langfuse Cloud Backend: If the issue seems to be related to the Langfuse Cloud backend, reaching out to Langfuse support might be necessary. They can investigate the backend logs and processing pipelines to identify any issues.
5. Adjust Asynchronous Context Handling: Ensure that the asynchronous context is correctly propagated throughout the agent's execution. This might involve using contextvars or other mechanisms to maintain the system prompt information across asynchronous calls.

In the meantime, a workaround could be to manually log the system prompt at the beginning of the test_system_prompt function. This would ensure that the prompt is at least visible in the logs, even if it's not displayed in the trace.

Conclusion

The bug where the system prompt is not displayed in the trace when using the Microsoft Agent Framework with Langfuse is a significant issue that hinders debugging and understanding of agent behavior. By following the steps outlined in this article, developers can reproduce the bug and gain a better understanding of its impact. The potential root causes and proposed solutions provide a starting point for further investigation and resolution.

Addressing this bug is crucial for ensuring that Langfuse provides a comprehensive and accurate view of agent executions. A complete trace, including the system prompt, enables developers to effectively monitor, debug, and optimize their agents. The collaboration between the bug reporter and the Langfuse team, along with a systematic approach to investigation and resolution, will help ensure a robust and reliable tracing experience. For more information on Langfuse and its features, visit the Langfuse Documentation.