docs(openai-agents): add content-capture and multi-agent samples

Author: nagkumar91

instrumentation-genai/opentelemetry-instrumentation-openai-agents/examples/content-capture/.env.example

@@ -0,0 +1,12 @@
+# Update this with your real OpenAI API key
+OPENAI_API_KEY=sk-YOUR_API_KEY
+
+# Uncomment and adjust if you use a non-default OTLP collector endpoint
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+# OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+
+OTEL_SERVICE_NAME=opentelemetry-python-openai-agents-content-capture
+OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=event_only
+
+# Set to ``no_content`` to opt out of capturing prompts and completions
+# OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=no_content

instrumentation-genai/opentelemetry-instrumentation-openai-agents/examples/content-capture/README.rst

@@ -0,0 +1,39 @@
+OpenTelemetry OpenAI Agents Content Capture Example
+===================================================
+
+This example highlights how to customize OpenAI Agents instrumentation to
+capture prompts, responses, and tool payloads. By setting
+``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=event_only`` the sample
+records message content as span events without duplicating it on span
+attributes. Use ``span_and_event`` (default) or ``span_only`` for alternative
+capture modes, or ``no_content`` to disable capture entirely. Boolean strings
+such as ``true``/``false`` are also accepted.
+
+Setup
+-----
+
+1. Copy `.env.example <.env.example>`_ to `.env` and update ``OPENAI_API_KEY``.
+   Adjust the OTLP endpoint variables if you export somewhere other than
+   ``http://localhost:4317``.
+2. Create a virtual environment and install the dependencies:
+
+   ::
+
+       python3 -m venv .venv
+       source .venv/bin/activate
+       pip install "python-dotenv[cli]"
+       pip install -r requirements.txt
+
+Run
+---
+
+Execute the sample and inspect the exported telemetry to see prompts, tool
+arguments, and responses attached as span events:
+
+::
+
+    dotenv run -- python main.py
+
+Set the ``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` environment
+variable to the capture mode you want (``span_and_event`` by default, or
+``span_only``/``event_only``/``no_content``) before running the sample.

instrumentation-genai/opentelemetry-instrumentation-openai-agents/examples/content-capture/main.py

@@ -0,0 +1,65 @@
+# pylint: skip-file
+"""Content capture OpenAI Agents instrumentation example."""
+
+from __future__ import annotations
+
+from agents import Agent, Runner, function_tool
+from dotenv import load_dotenv
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+    OTLPSpanExporter,
+)
+from opentelemetry.instrumentation.openai_agents import (
+    OpenAIAgentsInstrumentor,
+)
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+
+def configure_tracing() -> None:
+    """Configure the OpenTelemetry SDK and enable event-only capture."""
+
+    provider = TracerProvider()
+    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+    trace.set_tracer_provider(provider)
+
+    OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)
+
+
+@function_tool
+def lookup_weather(city: str) -> str:
+    """Return a canned weather response for the requested city."""
+
+    return f"The weather in {city} is mild with occasional sunshine."
+
+
+def run_agent() -> None:
+    """Create a story-driven packing advisor and execute one run."""
+
+    storyteller = Agent(
+        name="Packing Coach",
+        instructions=(
+            "Guide the traveler with tailored packing advice. Use the weather"
+            " tool for localized details and describe why each item matters."
+        ),
+        tools=[lookup_weather],
+    )
+
+    result = Runner.run_sync(
+        storyteller,
+        "I'm headed to Tokyo in the spring. Help me decide what to pack.",
+    )
+
+    print("Agent response:")
+    print(result.final_output)
+
+
+def main() -> None:
+    load_dotenv()
+    configure_tracing()
+    run_agent()
+
+
+if __name__ == "__main__":
+    main()

instrumentation-genai/opentelemetry-instrumentation-openai-agents/examples/content-capture/requirements.txt

@@ -0,0 +1,6 @@
+openai-agents~=0.3.3
+python-dotenv~=1.0
+
+opentelemetry-sdk~=1.36.0
+opentelemetry-exporter-otlp-proto-grpc~=1.36.0
+opentelemetry-instrumentation-openai-agents~=0.1.0.dev

instrumentation-genai/opentelemetry-instrumentation-openai-agents/examples/multi-agent/.env.example

@@ -0,0 +1,11 @@
+# Update this with your real OpenAI API key
+OPENAI_API_KEY=sk-YOUR_API_KEY
+
+# Uncomment and adjust if you use a non-default OTLP collector endpoint
+# OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
+# OTEL_EXPORTER_OTLP_PROTOCOL=grpc
+
+OTEL_SERVICE_NAME=opentelemetry-python-openai-agents-multi-agent
+
+# Set to ``no_content`` to opt out of capturing prompts and completions
+# OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=no_content

instrumentation-genai/opentelemetry-instrumentation-openai-agents/examples/multi-agent/README.rst

@@ -0,0 +1,36 @@
+OpenTelemetry OpenAI Agents Multi-Agent Example
+===============================================
+
+This example coordinates two specialized agents to produce a combined travel
+recommendation. The example captures prompts, responses, and tool interactions
+for both agents so you can explore multi-span traces in your GenAI telemetry
+backend.
+
+Setup
+-----
+
+1. Copy `.env.example <.env.example>`_ to `.env` and update ``OPENAI_API_KEY``.
+   Adjust the OTLP endpoint variables as needed for your collector.
+2. Create a virtual environment and install the dependencies:
+
+   ::
+
+       python3 -m venv .venv
+       source .venv/bin/activate
+       pip install "python-dotenv[cli]"
+       pip install -r requirements.txt
+
+Run
+---
+
+Launch both agents and examine the spans they generate:
+
+::
+
+    dotenv run -- python main.py
+
+Set ``OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT`` to ``span_only`` or
+``event_only`` to limit capture, or to ``no_content`` to suppress prompts and
+responses entirely for this scenario. Leaving it unset records content in both
+span attributes and events. Boolean strings such as ``true``/``false`` are also
+accepted.

instrumentation-genai/opentelemetry-instrumentation-openai-agents/examples/multi-agent/main.py

@@ -0,0 +1,88 @@
+# pylint: skip-file
+"""Multi-agent OpenAI Agents instrumentation example."""
+
+from __future__ import annotations
+
+from agents import Agent, Runner, function_tool
+from dotenv import load_dotenv
+
+from opentelemetry import trace
+from opentelemetry.exporter.otlp.proto.grpc.trace_exporter import (
+    OTLPSpanExporter,
+)
+from opentelemetry.instrumentation.openai_agents import (
+    OpenAIAgentsInstrumentor,
+)
+from opentelemetry.sdk.trace import TracerProvider
+from opentelemetry.sdk.trace.export import BatchSpanProcessor
+
+
+def configure_tracing() -> None:
+    """Configure tracing with the default content capture settings."""
+
+    provider = TracerProvider()
+    provider.add_span_processor(BatchSpanProcessor(OTLPSpanExporter()))
+    trace.set_tracer_provider(provider)
+
+    OpenAIAgentsInstrumentor().instrument(tracer_provider=provider)
+
+
+@function_tool
+def lookup_weather(city: str) -> str:
+    """Return a canned weekend forecast for the requested city."""
+
+    return f"Expect pleasant spring weather in {city} with cool evenings."
+
+
+@function_tool
+def find_dining(city: str) -> str:
+    """Return a canned dining suggestion for the requested city."""
+
+    return (
+        f"Reserve a table at a neighborhood izakaya in {city} for fresh seafood"
+        " and seasonal specials."
+    )
+
+
+def run_team() -> None:
+    """Coordinate two agents and show their combined guidance."""
+
+    travel_planner = Agent(
+        name="Travel Planner",
+        instructions=(
+            "Design a short itinerary with highlights and a quick travel tip."
+        ),
+        tools=[lookup_weather],
+    )
+
+    dining_expert = Agent(
+        name="Dining Expert",
+        instructions=(
+            "Recommend a memorable dining experience that complements the"
+            " travel plan provided."
+        ),
+        tools=[find_dining],
+    )
+
+    traveler_question = "I'm visiting Kyoto for a long weekend. Any advice?"
+
+    itinerary = Runner.run_sync(travel_planner, traveler_question)
+    dining = Runner.run_sync(
+        dining_expert,
+        f"Given this plan: {itinerary.final_output}\nSuggest food options.",
+    )
+
+    print("Travel planner response:")
+    print(itinerary.final_output)
+    print("\nDining expert response:")
+    print(dining.final_output)
+
+
+def main() -> None:
+    load_dotenv()
+    configure_tracing()
+    run_team()
+
+
+if __name__ == "__main__":
+    main()

instrumentation-genai/opentelemetry-instrumentation-openai-agents/examples/multi-agent/requirements.txt

@@ -0,0 +1,6 @@
+openai-agents~=0.3.3
+python-dotenv~=1.0
+
+opentelemetry-sdk~=1.36.0
+opentelemetry-exporter-otlp-proto-grpc~=1.36.0
+opentelemetry-instrumentation-openai-agents~=0.1.0.dev