splunk-ao-a2a 0.1.0__tar.gz

splunk_ao_a2a-0.1.0/.gitignore

@@ -0,0 +1,186 @@
+.DS_STORE
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+.idea/
+
+# PyPI configuration file
+.pypirc
+
+node_modules/
+
+.ruff_cache/
+
+.python-version
+.vscode/
+
+# PyDoc generated docs
+.generated_docs/
+
+# Local-only working notes / scratch dir (not for git)
+.local/

splunk_ao_a2a-0.1.0/CHANGELOG.md

@@ -0,0 +1,14 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- Added automatic OpenTelemetry instrumentation for A2A client and server
+  operations.
+- Added W3C trace-context propagation through A2A message metadata so remote
+  agents participate in one distributed trace.
+- Added A2A task and context correlation, session grouping, and optional
+  message-content capture.
+- Added deployment-aware OTLP export for Splunk Observability Cloud and
+  standalone Agent Observability through the core `splunk-ao` SDK.

splunk_ao_a2a-0.1.0/PKG-INFO

@@ -0,0 +1,309 @@
+Metadata-Version: 2.4
+Name: splunk-ao-a2a
+Version: 0.1.0
+Summary: Splunk AO observability auto-instrumentation for A2A (Agent-to-Agent) protocol
+Project-URL: Repository, https://github.com/splunk/splunk-ao-python
+Author-email: "Splunk Inc." <team@splunk.com>
+License: Apache-2.0
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.15,>=3.11
+Requires-Dist: a2a-sdk<1.0.0,>=0.3.0
+Requires-Dist: opentelemetry-api>=1.38.0
+Requires-Dist: opentelemetry-sdk>=1.38.0
+Requires-Dist: splunk-ao<1.0.0,>=0.1.0
+Description-Content-Type: text/markdown
+
+# splunk-ao-a2a
+
+[![PyPI version](https://img.shields.io/pypi/v/splunk-ao-a2a.svg)](https://pypi.org/project/splunk-ao-a2a/)
+[![Python versions](https://img.shields.io/pypi/pyversions/splunk-ao-a2a.svg)](https://pypi.org/project/splunk-ao-a2a/)
+[![License](https://img.shields.io/pypi/l/splunk-ao-a2a.svg)](https://github.com/splunk/splunk-ao-python/blob/main/LICENSE)
+
+Splunk AO observability for [A2A (Agent-to-Agent)](https://github.com/google/A2A) protocol interactions. Automatic tracing of agent-to-agent calls, task lifecycle, and cross-agent distributed trace correlation.
+
+## How It Works
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│                        Single Distributed Trace                      │
+├──────────────────────────────────────────────────────────────────────┤
+│                                                                      │
+│  ┌─────────────────────┐    A2A Protocol     ┌────────────────────┐  │
+│  │  Orchestrator Agent │    (JSON-RPC)       │  Researcher Agent  │  │
+│  │                     │                     │                    │  │
+│  │  plan               │  send_message ──>   │  on_message_send   │  │
+│  │  delegate ──────────┼──────────────────>  │    invoke LLM      │  │
+│  │  synthesize         │  <── stream events  │    call tools      │  │
+│  └──────────┬──────────┘                     └─────────┬──────────┘  │
+│             │                                          │             │
+│             │          OpenTelemetry Spans             │             │
+│             └─────────────────┬────────────────────────┘             │
+│                               │                                      │
+│                    ┌──────────▼──────────┐                           │
+│                    │     Splunk AO       │                           │
+│                    │  (Trace Explorer)   │                           │
+│                    └─────────────────────┘                           │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+`splunk-ao-a2a` instruments both the **client** (outbound calls) and **server** (inbound requests) sides of the A2A protocol. Trace context is propagated through A2A message metadata so all agents appear in a single distributed trace in Splunk AO.
+
+## Installation
+
+```bash
+pip install splunk-ao-a2a
+```
+
+**Requirements:** Python 3.11+, Splunk AO standalone or Splunk Observability Cloud credentials, and [a2a-sdk](https://pypi.org/project/a2a-sdk/) 0.3+
+
+## Quick Start
+
+```python
+from splunk_ao.otel import add_splunk_ao_span_processor
+from splunk_ao_a2a import A2AInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+
+provider = TracerProvider()
+add_splunk_ao_span_processor(provider)
+A2AInstrumentor().instrument(tracer_provider=provider, agent_name="orchestrator")
+
+try:
+    run_application()
+finally:
+    provider.shutdown()
+```
+
+Once instrumented, all `a2a-sdk` client and server interactions produce OTel spans automatically.
+
+## Configuration
+
+| Parameter | Description |
+|-----------|-------------|
+| `tracer_provider` | OTel `TracerProvider` instance. Falls back to the global provider if not specified. |
+| `agent_name` | Name of this agent, set on spans as `gen_ai.agent.name`. |
+| `capture_content` | Set to `False` to disable capturing message content (e.g. for PII compliance). |
+
+For standalone Splunk AO:
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `SPLUNK_AO_API_KEY` | Splunk AO API key (required) |
+| `SPLUNK_AO_CONSOLE_URL` | Splunk AO console URL (required for self-hosted deployments, e.g. `http://localhost:8088`) |
+| `SPLUNK_AO_API_URL` | Explicit API URL (optional; otherwise derived from the console URL) |
+| `SPLUNK_AO_PROJECT` | Project name |
+| `SPLUNK_AO_AGENT_STREAM` | Agent Stream name |
+
+For Splunk Observability Cloud:
+
+| Environment Variable | Description |
+|---------------------|-------------|
+| `SPLUNK_AO_REALM` | Observability Cloud realm (required) |
+| `SPLUNK_AO_O11Y_TOKEN` | O11y ingest token used for OTLP export (required) |
+| `SPLUNK_AO_O11Y_API_TOKEN` | Dedicated O11y API token for core SDK CRUD operations (optional) |
+| `SPLUNK_AO_PROJECT` | Project name |
+| `SPLUNK_AO_AGENT_STREAM` | Agent Stream name |
+
+Applications should configure Project and Agent Stream routing by name.
+The same Python setup works for both deployments; only the environment changes.
+
+## Features
+
+### Client & Server Instrumentation
+
+The instrumentor patches both sides of the A2A protocol:
+
+**Client-side** (outbound calls): `send_message`, `get_task`, `cancel_task`, `get_card`
+
+**Server-side** (inbound requests): `on_message_send`, `on_message_send_stream`
+
+### Cross-Agent Distributed Tracing
+
+When Agent A calls Agent B, trace context is propagated through A2A message metadata. The receiving agent joins the caller's trace, so both agents appear in a single distributed trace in Splunk AO.
+
+### Session Tracking
+
+A2A's `context_id` is mapped to `session.id`, grouping all interactions within the same conversation into a Splunk AO session.
+
+### Disabling Instrumentation
+
+```python
+instrumentor = A2AInstrumentor()
+instrumentor.instrument(tracer_provider=provider, agent_name="my-agent")
+
+# Restore original a2a-sdk behavior
+instrumentor.uninstrument()
+```
+
+## Multi-Agent Example
+
+Add distributed tracing to your multi-agent A2A workflow with just 4 lines of code. The rest is your standard agent logic — no changes needed.
+
+```python
+import asyncio
+import uuid
+
+import httpx
+import uvicorn
+from a2a.client import ClientConfig, ClientFactory
+from a2a.server.agent_execution import AgentExecutor, RequestContext
+from a2a.server.apps.jsonrpc.starlette_app import A2AStarletteApplication
+from a2a.server.events import EventQueue, InMemoryQueueManager
+from a2a.server.request_handlers.default_request_handler import DefaultRequestHandler
+from a2a.server.tasks import InMemoryTaskStore
+from a2a.types import (
+    AgentCapabilities, AgentCard, AgentSkill, Message, Role,
+    TaskState, TaskStatus, TaskStatusUpdateEvent, TextPart,
+)
+from splunk_ao.otel import add_splunk_ao_span_processor
+from splunk_ao_a2a import A2AInstrumentor
+from langchain.agents import create_agent
+from langchain_core.tools import tool
+from langchain_openai import ChatOpenAI
+from langgraph.graph import END, START, StateGraph
+from opentelemetry.instrumentation.langchain import LangchainInstrumentor
+from opentelemetry.sdk.trace import TracerProvider
+from starlette.applications import Starlette
+from typing_extensions import TypedDict
+
+# ---- Only 4 lines needed for full distributed tracing ----
+provider = TracerProvider()
+add_splunk_ao_span_processor(provider)
+A2AInstrumentor().instrument(tracer_provider=provider, agent_name="orchestrator")
+LangchainInstrumentor().instrument(tracer_provider=provider)
+
+
+# ---- Everything below is your standard agent code ----
+
+llm = ChatOpenAI(model="gpt-4o-mini")
+
+# Researcher agent — standard LangChain agent served over A2A
+
+@tool
+def search_kb(query: str) -> str:
+    """Search the travel knowledge base."""
+    if "paris" in query.lower():
+        return "Eiffel Tower 330m, Louvre 9.6M visitors/yr, 20 arrondissements."
+    return f"No results for: {query}"
+
+researcher = create_agent(
+    llm, [search_kb],
+    system_prompt="Use search_kb to find facts, then summarize for a traveler.",
+)
+
+CARD = AgentCard(
+    name="researcher", description="Travel researcher", url="http://localhost:9867",
+    version="1.0.0", capabilities=AgentCapabilities(streaming=True),
+    default_input_modes=["text/plain"], default_output_modes=["text/plain"],
+    skills=[AgentSkill(id="qa", name="Q&A", description="Answer questions", tags=[])],
+)
+
+class ResearcherExecutor(AgentExecutor):
+    async def execute(self, ctx: RequestContext, queue: EventQueue) -> None:
+        result = await researcher.ainvoke({"messages": [("user", ctx.get_user_input())]})
+        await queue.enqueue_event(TaskStatusUpdateEvent(
+            task_id=ctx.task_id, context_id=ctx.context_id, final=True,
+            status=TaskStatus(state=TaskState.completed, message=Message(
+                message_id=str(uuid.uuid4()), role=Role.agent,
+                parts=[TextPart(text=result["messages"][-1].content or "")],
+            )),
+        ))
+
+    async def cancel(self, ctx: RequestContext, queue: EventQueue) -> None:
+        await queue.enqueue_event(TaskStatusUpdateEvent(
+            task_id=ctx.task_id, context_id=ctx.context_id, final=True,
+            status=TaskStatus(state=TaskState.canceled),
+        ))
+
+# Orchestrator — standard LangGraph StateGraph
+
+class State(TypedDict):
+    user_query: str
+    skills: list[str]
+    research_query: str
+    response: str
+    plan: str
+
+def build_orchestrator(client):
+    async def discover(state: State) -> dict:
+        card = await client.get_card()
+        return {"skills": [s.name for s in card.skills]}
+
+    async def plan(state: State) -> dict:
+        result = await create_agent(llm,
+            system_prompt="Formulate a travel research question. Reply with ONLY the question.",
+        ).ainvoke({"messages": [("user", state["user_query"])]})
+        return {"research_query": result["messages"][-1].content}
+
+    async def delegate(state: State) -> dict:
+        msg = Message(message_id=str(uuid.uuid4()), role=Role.user,
+            parts=[TextPart(text=state["research_query"])], context_id="session-1")
+        async for event in client.send_message(msg):
+            if isinstance(event, tuple):
+                task = event[0]
+                if task.status and task.status.state == TaskState.completed and task.status.message:
+                    return {"response": getattr(task.status.message.parts[0].root, "text", "")}
+        return {"response": ""}
+
+    async def synthesize(state: State) -> dict:
+        result = await create_agent(llm,
+            system_prompt="Create a brief 3-day itinerary from the research.",
+        ).ainvoke({"messages": [("user", f"Research:\n{state['response']}\n\nCreate itinerary.")]})
+        return {"plan": result["messages"][-1].content}
+
+    graph = StateGraph(State)
+    graph.add_node("discover", discover)
+    graph.add_node("plan", plan)
+    graph.add_node("delegate", delegate)
+    graph.add_node("synthesize", synthesize)
+    graph.add_edge(START, "discover")
+    graph.add_edge("discover", "plan")
+    graph.add_edge("plan", "delegate")
+    graph.add_edge("delegate", "synthesize")
+    graph.add_edge("synthesize", END)
+    return graph.compile()
+
+# Run both agents
+
+async def main():
+    app = Starlette()
+    A2AStarletteApplication(
+        agent_card=CARD,
+        http_handler=DefaultRequestHandler(
+            agent_executor=ResearcherExecutor(),
+            task_store=InMemoryTaskStore(), queue_manager=InMemoryQueueManager(),
+        ),
+    ).add_routes_to_app(app)
+    server = uvicorn.Server(uvicorn.Config(app, port=9867, log_level="warning"))
+    server_task = asyncio.create_task(server.serve())
+    await asyncio.sleep(1)
+
+    client = ClientFactory(
+        config=ClientConfig(streaming=True, httpx_client=httpx.AsyncClient(timeout=httpx.Timeout(120))),
+    ).create(CARD)
+    result = await build_orchestrator(client).ainvoke(
+        {"user_query": "Plan a 3-day trip to Paris", "skills": [], "research_query": "", "response": "", "plan": ""},
+    )
+    print(result["plan"])
+
+    server.should_exit = True
+    await server_task
+    provider.shutdown()
+
+if __name__ == "__main__":
+    # Set environment variables: SPLUNK_AO_API_KEY, OPENAI_API_KEY
+    asyncio.run(main())
+```
+
+## Resources
+
+- [Splunk AO Documentation](https://agent-observability-docs.splunk.com)
+- [A2A Protocol Specification](https://a2a-protocol.org)
+- [a2a-sdk Documentation](https://pypi.org/project/a2a-sdk)
+
+## License
+
+Apache-2.0