agent-did-semantic-kernel 1.0.0rc1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (23) hide show
  1. agent_did_semantic_kernel-1.0.0rc1/PKG-INFO +346 -0
  2. agent_did_semantic_kernel-1.0.0rc1/README.md +311 -0
  3. agent_did_semantic_kernel-1.0.0rc1/pyproject.toml +75 -0
  4. agent_did_semantic_kernel-1.0.0rc1/setup.cfg +4 -0
  5. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/__init__.py +49 -0
  6. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/config.py +30 -0
  7. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/context.py +42 -0
  8. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/integration.py +148 -0
  9. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/observability.py +340 -0
  10. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/runtime.py +87 -0
  11. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/sanitization.py +101 -0
  12. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/snapshot.py +52 -0
  13. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/tools.py +530 -0
  14. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel.egg-info/PKG-INFO +346 -0
  15. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel.egg-info/SOURCES.txt +21 -0
  16. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel.egg-info/dependency_links.txt +1 -0
  17. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel.egg-info/requires.txt +18 -0
  18. agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel.egg-info/top_level.txt +1 -0
  19. agent_did_semantic_kernel-1.0.0rc1/tests/test_context.py +35 -0
  20. agent_did_semantic_kernel-1.0.0rc1/tests/test_integration.py +71 -0
  21. agent_did_semantic_kernel-1.0.0rc1/tests/test_observability.py +203 -0
  22. agent_did_semantic_kernel-1.0.0rc1/tests/test_runtime_smoke.py +160 -0
  23. agent_did_semantic_kernel-1.0.0rc1/tests/test_security.py +60 -0
@@ -0,0 +1,346 @@
1
+ Metadata-Version: 2.4
2
+ Name: agent-did-semantic-kernel
3
+ Version: 1.0.0rc1
4
+ Summary: Semantic Kernel Python integration for Agent-DID identities, tools, context injection and secure opt-in operations.
5
+ Author: Agent-DID contributors
6
+ License-Expression: Apache-2.0
7
+ Project-URL: Homepage, https://github.com/edisonduran/agent-did
8
+ Project-URL: Repository, https://github.com/edisonduran/agent-did
9
+ Keywords: agent-did,semantic-kernel,python,did,identity,tool-calling
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Intended Audience :: Developers
12
+ Classifier: Programming Language :: Python :: 3
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Topic :: Security :: Cryptography
17
+ Classifier: Typing :: Typed
18
+ Requires-Python: >=3.10
19
+ Description-Content-Type: text/markdown
20
+ Requires-Dist: agent-did-sdk==1.0.0rc1
21
+ Requires-Dist: pydantic>=2.0
22
+ Provides-Extra: dev
23
+ Requires-Dist: build>=1.2; extra == "dev"
24
+ Requires-Dist: opentelemetry-api<2.0,>=1.30; extra == "dev"
25
+ Requires-Dist: opentelemetry-sdk<2.0,>=1.30; extra == "dev"
26
+ Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
27
+ Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == "dev"
28
+ Requires-Dist: ruff>=0.4; extra == "dev"
29
+ Requires-Dist: mypy>=1.10; extra == "dev"
30
+ Provides-Extra: observability
31
+ Requires-Dist: opentelemetry-api<2.0,>=1.30; extra == "observability"
32
+ Requires-Dist: opentelemetry-sdk<2.0,>=1.30; extra == "observability"
33
+ Provides-Extra: runtime
34
+ Requires-Dist: semantic-kernel<2.0.0,>=1.41.0; extra == "runtime"
35
+
36
+ # agent-did-semantic-kernel
37
+
38
+ Integracion funcional de Agent-DID para Semantic Kernel con foco en Python.
39
+
40
+ Esta variante reutiliza el SDK Python real de Agent-DID para snapshot de identidad, resolucion, verificacion, firma opt-in, contexto de sesion, hooks tipo middleware, observabilidad estructurada y un adaptador especializado a OpenTelemetry sin exponer secretos al runtime visible por el modelo.
41
+
42
+ ## Estado
43
+
44
+ - Estado actual: `functional`
45
+ - Roadmap: F2-04
46
+ - Lenguaje objetivo: Python
47
+ - Dependencia previa resuelta: SDK Python de Agent-DID
48
+ - Implementacion: funcional para tools base, contexto de identidad, middleware ligero, observabilidad saneada y validacion avanzada contra host real
49
+
50
+ El paquete ya expone una factory publica, tools reutilizables, helpers para contexto y middleware, observabilidad vendor-neutral, un camino especializado con OpenTelemetry y defaults seguros. Las operaciones sensibles siguen siendo opt-in: firma HTTP, firma arbitraria, rotacion de claves e historial documental no se habilitan por defecto.
51
+
52
+ Con el estado actual, la claim correcta para F2-04 ya no es solo "paridad funcional base": el paquete tiene paridad operativa completa con LangChain Python dentro del alcance gobernado por este repositorio para runtime, observabilidad y recipes operativas.
53
+
54
+ ## Hallazgos tecnicos confirmados
55
+
56
+ Segun la documentacion oficial y el runtime validado en CI, Semantic Kernel expone al menos estas superficies utiles para Agent-DID:
57
+
58
+ - `Kernel` como host principal para plugins y funciones.
59
+ - `KernelPlugin` y `kernel_function(...)` para registrar tools Agent-DID con schemas compatibles.
60
+ - `Kernel.invoke(...)` para ejecutar tools a traves del runtime real sin requerir una corrida LLM completa.
61
+ - `ChatCompletionAgent` como host agentico validado en la recipe operativa y el smoke test.
62
+ - composicion Python-first sin obligar una dependencia runtime en la instalacion por defecto.
63
+
64
+ ## Decision de lenguaje
65
+
66
+ La decision implementada para F2-04 es:
67
+
68
+ 1. Implementacion en Python.
69
+ 2. Dependencia explicita del SDK Python existente de Agent-DID.
70
+ 3. Sin compromiso de implementacion JS en esta fase.
71
+
72
+ ## Objetivo
73
+
74
+ Integrar Agent-DID como capa de identidad verificable para agentes ejecutados sobre Semantic Kernel, de forma equivalente a lo ya disponible para LangChain:
75
+
76
+ - inyectar DID, controlador, capacidades y clave activa en el contexto operativo del agente,
77
+ - exponer herramientas para inspeccionar identidad, verificar firmas y resolver documentos,
78
+ - habilitar firma de payloads o solicitudes HTTP solo mediante opt-in,
79
+ - mantener la clave privada fuera del contexto visible para el modelo.
80
+
81
+ ## Uso rapido
82
+
83
+ ```python
84
+ from agent_did_semantic_kernel import create_agent_did_semantic_kernel_integration
85
+ from agent_did_sdk import AgentIdentity, AgentIdentityConfig, CreateAgentParams
86
+
87
+ identity = AgentIdentity(AgentIdentityConfig(signer_address="0x1234567890123456789012345678901234567890"))
88
+ runtime_identity = await identity.create(
89
+ CreateAgentParams(
90
+ name="semantic_kernel_assistant",
91
+ core_model="gpt-4.1-mini",
92
+ system_prompt="Eres un agente verificable y trazable.",
93
+ capabilities=["identity:resolve", "signature:verify"],
94
+ )
95
+ )
96
+
97
+ integration = create_agent_did_semantic_kernel_integration(
98
+ agent_identity=identity,
99
+ runtime_identity=runtime_identity,
100
+ expose={"sign_http": True, "document_history": True},
101
+ )
102
+
103
+ agent_kwargs = integration.create_agent_kwargs("Usa herramientas Agent-DID cuando aporten evidencia.")
104
+ context_middleware = integration.create_context_middleware()
105
+ session_context = context_middleware({"session_id": "demo"})
106
+ ```
107
+
108
+ El bundle devuelto incluye:
109
+
110
+ - `tools`: wrappers ligeros con `invoke(...)` y `ainvoke(...)`
111
+ - `get_current_identity()` y `get_current_document()`
112
+ - `compose_instructions(...)`
113
+ - `create_agent_kwargs(...)` para entregar `tools`, `instructions` y `context`
114
+ - `create_session_context(...)` para inyectar identidad Agent-DID en session state
115
+ - `create_context_middleware(...)` para hooks ligeros de enriquecimiento de contexto
116
+ - `create_semantic_kernel_plugin(...)` para registrar las tools en un runtime real de `semantic-kernel`
117
+
118
+ La API publica tambien exporta el alias conceptual `createAgentDidSemanticKernelIntegration(...)` para mantener continuidad con los artefactos de diseno, aunque la superficie Python-first recomendada es `create_agent_did_semantic_kernel_integration(...)`.
119
+
120
+ ## Runtime real con semantic-kernel
121
+
122
+ La integracion sigue siendo liviana por defecto, pero ahora expone un extra opcional `runtime` para validar y usar un runtime real de Semantic Kernel mediante `semantic-kernel`.
123
+
124
+ ```bash
125
+ python -m pip install -e ".[runtime]"
126
+ ```
127
+
128
+ Ejemplo minimo de registro sobre el runtime real:
129
+
130
+ ```python
131
+ from semantic_kernel.agents.chat_completion.chat_completion_agent import ChatCompletionAgent
132
+ from semantic_kernel.kernel import Kernel
133
+
134
+ plugin = integration.create_semantic_kernel_plugin(plugin_name="agent_did")
135
+ kernel = Kernel()
136
+ kernel.add_plugin(plugin)
137
+
138
+ agent = ChatCompletionAgent(
139
+ name="Verifier",
140
+ instructions=integration.compose_instructions("Usa Agent-DID cuando necesites evidencia verificable."),
141
+ kernel=kernel,
142
+ plugins=[plugin],
143
+ )
144
+
145
+ identity_result = await kernel.invoke(
146
+ function_name="agent_did_get_current_identity",
147
+ plugin_name="agent_did",
148
+ )
149
+ ```
150
+
151
+ Ese path no fuerza ejecucion LLM en CI. La validacion de paridad ahora cubre tres cosas mas utiles para esta fase:
152
+
153
+ - que `semantic-kernel` acepte el plugin generado por la integracion
154
+ - que una secuencia multi-tool real pueda invocarse a traves del runtime
155
+ - que el contexto inyectado y la identidad activa sigan consistentes a traves de rotacion de claves, verificacion y consulta de historial
156
+
157
+ ## Recetas operativas
158
+
159
+ ### Receta 1: runtime real con observabilidad compuesta
160
+
161
+ Use esta receta cuando quiera validar en local tres cosas a la vez sin depender de una corrida LLM completa:
162
+
163
+ - registro real del plugin en `semantic-kernel`
164
+ - invocacion de una tool Agent-DID desde `Kernel.invoke(...)`
165
+ - fan-out de observabilidad a memoria y logging JSON saneado
166
+
167
+ Ejecute:
168
+
169
+ ```bash
170
+ cd integrations/semantic-kernel
171
+ python -m pip install -e .[dev]
172
+ python -m pip install -e .[runtime]
173
+ python examples/agent_did_semantic_kernel_operational_recipe_example.py
174
+ ```
175
+
176
+ La recipe:
177
+
178
+ - crea una identidad efimera con `InMemoryAgentRegistry`
179
+ - compone `events.append` con `create_json_logger_event_handler(...)`
180
+ - registra el plugin Agent-DID en `Kernel`
181
+ - instancia `ChatCompletionAgent` sin requerir ejecucion de modelo
182
+ - invoca `agent_did_sign_payload` para demostrar compatibilidad de runtime y redaccion de observabilidad
183
+
184
+ Artefacto runnable asociado:
185
+
186
+ - `examples/agent_did_semantic_kernel_operational_recipe_example.py`
187
+
188
+ ### Receta 2: observabilidad compuesta con OpenTelemetry
189
+
190
+ Use esta receta cuando quiera proyectar los eventos Agent-DID a tres sinks a la vez sin cambiar la factory publica:
191
+
192
+ - memoria local para debugging rapido
193
+ - logging JSON saneado
194
+ - spans OpenTelemetry con mapping deterministico y redaccion preservada
195
+
196
+ Ejecute:
197
+
198
+ ```bash
199
+ cd integrations/semantic-kernel
200
+ python -m pip install -e .[dev]
201
+ python examples/agent_did_semantic_kernel_composed_observability_example.py
202
+ ```
203
+
204
+ La recipe:
205
+
206
+ - crea un `TracerProvider` local con `InMemorySpanExporter`
207
+ - compone callback local, JSON logging y `create_opentelemetry_event_handler(...)`
208
+ - invoca varias tools para demostrar que la redaccion se conserva en los tres sinks
209
+ - imprime spans terminados con atributos saneados para inspeccion local
210
+
211
+ Artefacto runnable asociado:
212
+
213
+ - `examples/agent_did_semantic_kernel_composed_observability_example.py`
214
+
215
+ ### Receta 3: recipe operativa de produccion sin corrida LLM obligatoria
216
+
217
+ Use esta receta cuando quiera validar una secuencia mas cercana a operacion real sin depender de un modelo externo:
218
+
219
+ - contexto inicial de sesion
220
+ - firma de payload
221
+ - verificacion criptografica
222
+ - rotacion de clave activa
223
+ - historial documental
224
+ - firma HTTP opt-in
225
+ - observabilidad compuesta con OpenTelemetry y JSON logging
226
+
227
+ Ejecute:
228
+
229
+ ```bash
230
+ cd integrations/semantic-kernel
231
+ python -m pip install -e .[runtime,observability]
232
+ set RUN_SEMANTIC_KERNEL_PRODUCTION_EXAMPLE=1
233
+ python examples/agent_did_semantic_kernel_production_recipe_example.py
234
+ ```
235
+
236
+ Artefacto runnable asociado:
237
+
238
+ - `examples/agent_did_semantic_kernel_production_recipe_example.py`
239
+
240
+ ## Observabilidad
241
+
242
+ La factory publica acepta instrumentacion opcional sin acoplar el paquete a un backend especifico:
243
+
244
+ ```python
245
+ import logging
246
+
247
+ from agent_did_semantic_kernel import create_agent_did_semantic_kernel_integration
248
+ from agent_did_semantic_kernel.observability import compose_event_handlers, create_json_logger_event_handler
249
+
250
+ logger = logging.getLogger("agent_did_semantic_kernel")
251
+ events = []
252
+
253
+ integration = create_agent_did_semantic_kernel_integration(
254
+ agent_identity=agent_identity,
255
+ runtime_identity=runtime_identity,
256
+ expose={"sign_http": True, "sign_payload": True},
257
+ observability_handler=compose_event_handlers(
258
+ events.append,
259
+ create_json_logger_event_handler(logger, extra_fields={"service": "agent-gateway"}),
260
+ ),
261
+ )
262
+ ```
263
+
264
+ Eventos emitidos:
265
+
266
+ - `agent_did.identity_snapshot.refreshed`
267
+ - `agent_did.tool.started`
268
+ - `agent_did.tool.succeeded`
269
+ - `agent_did.tool.failed`
270
+ - `agent_did.context.created`
271
+ - `agent_did.middleware.context_injected`
272
+
273
+ Si necesita una capa mas especializada que el callback o el logger JSON base, el paquete tambien expone un camino OpenTelemetry opt-in:
274
+
275
+ - `create_opentelemetry_tracer(...)`: obtiene un tracer compatible con la instalacion activa.
276
+ - `create_opentelemetry_event_handler(tracer, ...)`: proyecta eventos Agent-DID a spans OpenTelemetry saneados, incluyendo lifecycle de tools y eventos genericos.
277
+
278
+ Ejemplo minimo:
279
+
280
+ ```python
281
+ from opentelemetry.sdk.trace import TracerProvider
282
+ from opentelemetry.sdk.trace.export import SimpleSpanProcessor
283
+ from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
284
+
285
+ from agent_did_semantic_kernel.observability import (
286
+ compose_event_handlers,
287
+ create_json_logger_event_handler,
288
+ create_opentelemetry_event_handler,
289
+ create_opentelemetry_tracer,
290
+ )
291
+
292
+ provider = TracerProvider()
293
+ exporter = InMemorySpanExporter()
294
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
295
+ tracer = create_opentelemetry_tracer(tracer_provider=provider)
296
+
297
+ observability_handler = compose_event_handlers(
298
+ local_events.append,
299
+ create_json_logger_event_handler(logger, extra_fields={"sink": "json"}),
300
+ create_opentelemetry_event_handler(tracer, extra_fields={"sink": "otel"}),
301
+ )
302
+ ```
303
+
304
+ Este adaptador especializado:
305
+
306
+ - conserva redaccion de `payload`, `body`, `signature` y URLs sensibles
307
+ - mantiene mapping estable para `agent_did.tool.started`, `agent_did.tool.succeeded` y `agent_did.tool.failed`
308
+ - permite exportar spans a collectors reales o validarlos localmente con `InMemorySpanExporter`
309
+
310
+ ## Defaults seguros
311
+
312
+ - `current_identity`, `resolve_did` y `verify_signatures` quedan habilitados por defecto.
313
+ - `sign_http`, `sign_payload`, `rotate_keys` y `document_history` permanecen deshabilitados por defecto.
314
+ - `sign_http` rechaza esquemas no HTTP(S), credenciales embebidas y targets privados o loopback salvo opt-in explicito con `allow_private_network_targets=True`.
315
+ - El contexto de sesion y middleware nunca inyectan `agent_private_key` ni firma cruda.
316
+ - La observabilidad redacta `payload`, `body`, `signature`, `private_key`, `token` y headers sensibles por defecto.
317
+
318
+ ## Validacion local
319
+
320
+ ```bash
321
+ cd sdk-python
322
+ python -m pip install -e .[dev]
323
+ cd ../integrations/semantic-kernel
324
+ python -m pip install -e .[dev]
325
+ python -m ruff check src/ tests/ examples/
326
+ python -m mypy src/
327
+ python -m pytest tests/ -q
328
+ python -m pip install -e .[runtime,observability]
329
+ python -m pytest tests/test_runtime_smoke.py -q
330
+ python -m build
331
+ ```
332
+
333
+ La ruta anterior valida tanto la suite base como la cobertura avanzada de runtime real y la capa especializada de observabilidad.
334
+
335
+ ## Gobernanza de implementacion
336
+
337
+ - Checklist de implementacion: [../../docs/F2-04-Semantic-Kernel-Implementation-Checklist.md](../../docs/F2-04-Semantic-Kernel-Implementation-Checklist.md)
338
+ - Checklist de review recurrente: [../../docs/F2-04-Semantic-Kernel-Integration-Review-Checklist.md](../../docs/F2-04-Semantic-Kernel-Integration-Review-Checklist.md)
339
+ - Matriz de paridad: [../../docs/F2-04-Semantic-Kernel-Parity-Matrix.md](../../docs/F2-04-Semantic-Kernel-Parity-Matrix.md)
340
+ - Evaluacion de brecha de madurez: [../../docs/F2-04-Semantic-Kernel-Maturity-Gap-Assessment.md](../../docs/F2-04-Semantic-Kernel-Maturity-Gap-Assessment.md)
341
+
342
+ ## Referencias
343
+
344
+ - Implementacion de referencia actual: [../langchain/README.md](../langchain/README.md)
345
+ - Documento de diseno: [../../docs/F2-04-Semantic-Kernel-Integration-Design.md](../../docs/F2-04-Semantic-Kernel-Integration-Design.md)
346
+ - Documentacion oficial: https://github.com/microsoft/semantic-kernel
@@ -0,0 +1,311 @@
1
+ # agent-did-semantic-kernel
2
+
3
+ Integracion funcional de Agent-DID para Semantic Kernel con foco en Python.
4
+
5
+ Esta variante reutiliza el SDK Python real de Agent-DID para snapshot de identidad, resolucion, verificacion, firma opt-in, contexto de sesion, hooks tipo middleware, observabilidad estructurada y un adaptador especializado a OpenTelemetry sin exponer secretos al runtime visible por el modelo.
6
+
7
+ ## Estado
8
+
9
+ - Estado actual: `functional`
10
+ - Roadmap: F2-04
11
+ - Lenguaje objetivo: Python
12
+ - Dependencia previa resuelta: SDK Python de Agent-DID
13
+ - Implementacion: funcional para tools base, contexto de identidad, middleware ligero, observabilidad saneada y validacion avanzada contra host real
14
+
15
+ El paquete ya expone una factory publica, tools reutilizables, helpers para contexto y middleware, observabilidad vendor-neutral, un camino especializado con OpenTelemetry y defaults seguros. Las operaciones sensibles siguen siendo opt-in: firma HTTP, firma arbitraria, rotacion de claves e historial documental no se habilitan por defecto.
16
+
17
+ Con el estado actual, la claim correcta para F2-04 ya no es solo "paridad funcional base": el paquete tiene paridad operativa completa con LangChain Python dentro del alcance gobernado por este repositorio para runtime, observabilidad y recipes operativas.
18
+
19
+ ## Hallazgos tecnicos confirmados
20
+
21
+ Segun la documentacion oficial y el runtime validado en CI, Semantic Kernel expone al menos estas superficies utiles para Agent-DID:
22
+
23
+ - `Kernel` como host principal para plugins y funciones.
24
+ - `KernelPlugin` y `kernel_function(...)` para registrar tools Agent-DID con schemas compatibles.
25
+ - `Kernel.invoke(...)` para ejecutar tools a traves del runtime real sin requerir una corrida LLM completa.
26
+ - `ChatCompletionAgent` como host agentico validado en la recipe operativa y el smoke test.
27
+ - composicion Python-first sin obligar una dependencia runtime en la instalacion por defecto.
28
+
29
+ ## Decision de lenguaje
30
+
31
+ La decision implementada para F2-04 es:
32
+
33
+ 1. Implementacion en Python.
34
+ 2. Dependencia explicita del SDK Python existente de Agent-DID.
35
+ 3. Sin compromiso de implementacion JS en esta fase.
36
+
37
+ ## Objetivo
38
+
39
+ Integrar Agent-DID como capa de identidad verificable para agentes ejecutados sobre Semantic Kernel, de forma equivalente a lo ya disponible para LangChain:
40
+
41
+ - inyectar DID, controlador, capacidades y clave activa en el contexto operativo del agente,
42
+ - exponer herramientas para inspeccionar identidad, verificar firmas y resolver documentos,
43
+ - habilitar firma de payloads o solicitudes HTTP solo mediante opt-in,
44
+ - mantener la clave privada fuera del contexto visible para el modelo.
45
+
46
+ ## Uso rapido
47
+
48
+ ```python
49
+ from agent_did_semantic_kernel import create_agent_did_semantic_kernel_integration
50
+ from agent_did_sdk import AgentIdentity, AgentIdentityConfig, CreateAgentParams
51
+
52
+ identity = AgentIdentity(AgentIdentityConfig(signer_address="0x1234567890123456789012345678901234567890"))
53
+ runtime_identity = await identity.create(
54
+ CreateAgentParams(
55
+ name="semantic_kernel_assistant",
56
+ core_model="gpt-4.1-mini",
57
+ system_prompt="Eres un agente verificable y trazable.",
58
+ capabilities=["identity:resolve", "signature:verify"],
59
+ )
60
+ )
61
+
62
+ integration = create_agent_did_semantic_kernel_integration(
63
+ agent_identity=identity,
64
+ runtime_identity=runtime_identity,
65
+ expose={"sign_http": True, "document_history": True},
66
+ )
67
+
68
+ agent_kwargs = integration.create_agent_kwargs("Usa herramientas Agent-DID cuando aporten evidencia.")
69
+ context_middleware = integration.create_context_middleware()
70
+ session_context = context_middleware({"session_id": "demo"})
71
+ ```
72
+
73
+ El bundle devuelto incluye:
74
+
75
+ - `tools`: wrappers ligeros con `invoke(...)` y `ainvoke(...)`
76
+ - `get_current_identity()` y `get_current_document()`
77
+ - `compose_instructions(...)`
78
+ - `create_agent_kwargs(...)` para entregar `tools`, `instructions` y `context`
79
+ - `create_session_context(...)` para inyectar identidad Agent-DID en session state
80
+ - `create_context_middleware(...)` para hooks ligeros de enriquecimiento de contexto
81
+ - `create_semantic_kernel_plugin(...)` para registrar las tools en un runtime real de `semantic-kernel`
82
+
83
+ La API publica tambien exporta el alias conceptual `createAgentDidSemanticKernelIntegration(...)` para mantener continuidad con los artefactos de diseno, aunque la superficie Python-first recomendada es `create_agent_did_semantic_kernel_integration(...)`.
84
+
85
+ ## Runtime real con semantic-kernel
86
+
87
+ La integracion sigue siendo liviana por defecto, pero ahora expone un extra opcional `runtime` para validar y usar un runtime real de Semantic Kernel mediante `semantic-kernel`.
88
+
89
+ ```bash
90
+ python -m pip install -e ".[runtime]"
91
+ ```
92
+
93
+ Ejemplo minimo de registro sobre el runtime real:
94
+
95
+ ```python
96
+ from semantic_kernel.agents.chat_completion.chat_completion_agent import ChatCompletionAgent
97
+ from semantic_kernel.kernel import Kernel
98
+
99
+ plugin = integration.create_semantic_kernel_plugin(plugin_name="agent_did")
100
+ kernel = Kernel()
101
+ kernel.add_plugin(plugin)
102
+
103
+ agent = ChatCompletionAgent(
104
+ name="Verifier",
105
+ instructions=integration.compose_instructions("Usa Agent-DID cuando necesites evidencia verificable."),
106
+ kernel=kernel,
107
+ plugins=[plugin],
108
+ )
109
+
110
+ identity_result = await kernel.invoke(
111
+ function_name="agent_did_get_current_identity",
112
+ plugin_name="agent_did",
113
+ )
114
+ ```
115
+
116
+ Ese path no fuerza ejecucion LLM en CI. La validacion de paridad ahora cubre tres cosas mas utiles para esta fase:
117
+
118
+ - que `semantic-kernel` acepte el plugin generado por la integracion
119
+ - que una secuencia multi-tool real pueda invocarse a traves del runtime
120
+ - que el contexto inyectado y la identidad activa sigan consistentes a traves de rotacion de claves, verificacion y consulta de historial
121
+
122
+ ## Recetas operativas
123
+
124
+ ### Receta 1: runtime real con observabilidad compuesta
125
+
126
+ Use esta receta cuando quiera validar en local tres cosas a la vez sin depender de una corrida LLM completa:
127
+
128
+ - registro real del plugin en `semantic-kernel`
129
+ - invocacion de una tool Agent-DID desde `Kernel.invoke(...)`
130
+ - fan-out de observabilidad a memoria y logging JSON saneado
131
+
132
+ Ejecute:
133
+
134
+ ```bash
135
+ cd integrations/semantic-kernel
136
+ python -m pip install -e .[dev]
137
+ python -m pip install -e .[runtime]
138
+ python examples/agent_did_semantic_kernel_operational_recipe_example.py
139
+ ```
140
+
141
+ La recipe:
142
+
143
+ - crea una identidad efimera con `InMemoryAgentRegistry`
144
+ - compone `events.append` con `create_json_logger_event_handler(...)`
145
+ - registra el plugin Agent-DID en `Kernel`
146
+ - instancia `ChatCompletionAgent` sin requerir ejecucion de modelo
147
+ - invoca `agent_did_sign_payload` para demostrar compatibilidad de runtime y redaccion de observabilidad
148
+
149
+ Artefacto runnable asociado:
150
+
151
+ - `examples/agent_did_semantic_kernel_operational_recipe_example.py`
152
+
153
+ ### Receta 2: observabilidad compuesta con OpenTelemetry
154
+
155
+ Use esta receta cuando quiera proyectar los eventos Agent-DID a tres sinks a la vez sin cambiar la factory publica:
156
+
157
+ - memoria local para debugging rapido
158
+ - logging JSON saneado
159
+ - spans OpenTelemetry con mapping deterministico y redaccion preservada
160
+
161
+ Ejecute:
162
+
163
+ ```bash
164
+ cd integrations/semantic-kernel
165
+ python -m pip install -e .[dev]
166
+ python examples/agent_did_semantic_kernel_composed_observability_example.py
167
+ ```
168
+
169
+ La recipe:
170
+
171
+ - crea un `TracerProvider` local con `InMemorySpanExporter`
172
+ - compone callback local, JSON logging y `create_opentelemetry_event_handler(...)`
173
+ - invoca varias tools para demostrar que la redaccion se conserva en los tres sinks
174
+ - imprime spans terminados con atributos saneados para inspeccion local
175
+
176
+ Artefacto runnable asociado:
177
+
178
+ - `examples/agent_did_semantic_kernel_composed_observability_example.py`
179
+
180
+ ### Receta 3: recipe operativa de produccion sin corrida LLM obligatoria
181
+
182
+ Use esta receta cuando quiera validar una secuencia mas cercana a operacion real sin depender de un modelo externo:
183
+
184
+ - contexto inicial de sesion
185
+ - firma de payload
186
+ - verificacion criptografica
187
+ - rotacion de clave activa
188
+ - historial documental
189
+ - firma HTTP opt-in
190
+ - observabilidad compuesta con OpenTelemetry y JSON logging
191
+
192
+ Ejecute:
193
+
194
+ ```bash
195
+ cd integrations/semantic-kernel
196
+ python -m pip install -e .[runtime,observability]
197
+ set RUN_SEMANTIC_KERNEL_PRODUCTION_EXAMPLE=1
198
+ python examples/agent_did_semantic_kernel_production_recipe_example.py
199
+ ```
200
+
201
+ Artefacto runnable asociado:
202
+
203
+ - `examples/agent_did_semantic_kernel_production_recipe_example.py`
204
+
205
+ ## Observabilidad
206
+
207
+ La factory publica acepta instrumentacion opcional sin acoplar el paquete a un backend especifico:
208
+
209
+ ```python
210
+ import logging
211
+
212
+ from agent_did_semantic_kernel import create_agent_did_semantic_kernel_integration
213
+ from agent_did_semantic_kernel.observability import compose_event_handlers, create_json_logger_event_handler
214
+
215
+ logger = logging.getLogger("agent_did_semantic_kernel")
216
+ events = []
217
+
218
+ integration = create_agent_did_semantic_kernel_integration(
219
+ agent_identity=agent_identity,
220
+ runtime_identity=runtime_identity,
221
+ expose={"sign_http": True, "sign_payload": True},
222
+ observability_handler=compose_event_handlers(
223
+ events.append,
224
+ create_json_logger_event_handler(logger, extra_fields={"service": "agent-gateway"}),
225
+ ),
226
+ )
227
+ ```
228
+
229
+ Eventos emitidos:
230
+
231
+ - `agent_did.identity_snapshot.refreshed`
232
+ - `agent_did.tool.started`
233
+ - `agent_did.tool.succeeded`
234
+ - `agent_did.tool.failed`
235
+ - `agent_did.context.created`
236
+ - `agent_did.middleware.context_injected`
237
+
238
+ Si necesita una capa mas especializada que el callback o el logger JSON base, el paquete tambien expone un camino OpenTelemetry opt-in:
239
+
240
+ - `create_opentelemetry_tracer(...)`: obtiene un tracer compatible con la instalacion activa.
241
+ - `create_opentelemetry_event_handler(tracer, ...)`: proyecta eventos Agent-DID a spans OpenTelemetry saneados, incluyendo lifecycle de tools y eventos genericos.
242
+
243
+ Ejemplo minimo:
244
+
245
+ ```python
246
+ from opentelemetry.sdk.trace import TracerProvider
247
+ from opentelemetry.sdk.trace.export import SimpleSpanProcessor
248
+ from opentelemetry.sdk.trace.export.in_memory_span_exporter import InMemorySpanExporter
249
+
250
+ from agent_did_semantic_kernel.observability import (
251
+ compose_event_handlers,
252
+ create_json_logger_event_handler,
253
+ create_opentelemetry_event_handler,
254
+ create_opentelemetry_tracer,
255
+ )
256
+
257
+ provider = TracerProvider()
258
+ exporter = InMemorySpanExporter()
259
+ provider.add_span_processor(SimpleSpanProcessor(exporter))
260
+ tracer = create_opentelemetry_tracer(tracer_provider=provider)
261
+
262
+ observability_handler = compose_event_handlers(
263
+ local_events.append,
264
+ create_json_logger_event_handler(logger, extra_fields={"sink": "json"}),
265
+ create_opentelemetry_event_handler(tracer, extra_fields={"sink": "otel"}),
266
+ )
267
+ ```
268
+
269
+ Este adaptador especializado:
270
+
271
+ - conserva redaccion de `payload`, `body`, `signature` y URLs sensibles
272
+ - mantiene mapping estable para `agent_did.tool.started`, `agent_did.tool.succeeded` y `agent_did.tool.failed`
273
+ - permite exportar spans a collectors reales o validarlos localmente con `InMemorySpanExporter`
274
+
275
+ ## Defaults seguros
276
+
277
+ - `current_identity`, `resolve_did` y `verify_signatures` quedan habilitados por defecto.
278
+ - `sign_http`, `sign_payload`, `rotate_keys` y `document_history` permanecen deshabilitados por defecto.
279
+ - `sign_http` rechaza esquemas no HTTP(S), credenciales embebidas y targets privados o loopback salvo opt-in explicito con `allow_private_network_targets=True`.
280
+ - El contexto de sesion y middleware nunca inyectan `agent_private_key` ni firma cruda.
281
+ - La observabilidad redacta `payload`, `body`, `signature`, `private_key`, `token` y headers sensibles por defecto.
282
+
283
+ ## Validacion local
284
+
285
+ ```bash
286
+ cd sdk-python
287
+ python -m pip install -e .[dev]
288
+ cd ../integrations/semantic-kernel
289
+ python -m pip install -e .[dev]
290
+ python -m ruff check src/ tests/ examples/
291
+ python -m mypy src/
292
+ python -m pytest tests/ -q
293
+ python -m pip install -e .[runtime,observability]
294
+ python -m pytest tests/test_runtime_smoke.py -q
295
+ python -m build
296
+ ```
297
+
298
+ La ruta anterior valida tanto la suite base como la cobertura avanzada de runtime real y la capa especializada de observabilidad.
299
+
300
+ ## Gobernanza de implementacion
301
+
302
+ - Checklist de implementacion: [../../docs/F2-04-Semantic-Kernel-Implementation-Checklist.md](../../docs/F2-04-Semantic-Kernel-Implementation-Checklist.md)
303
+ - Checklist de review recurrente: [../../docs/F2-04-Semantic-Kernel-Integration-Review-Checklist.md](../../docs/F2-04-Semantic-Kernel-Integration-Review-Checklist.md)
304
+ - Matriz de paridad: [../../docs/F2-04-Semantic-Kernel-Parity-Matrix.md](../../docs/F2-04-Semantic-Kernel-Parity-Matrix.md)
305
+ - Evaluacion de brecha de madurez: [../../docs/F2-04-Semantic-Kernel-Maturity-Gap-Assessment.md](../../docs/F2-04-Semantic-Kernel-Maturity-Gap-Assessment.md)
306
+
307
+ ## Referencias
308
+
309
+ - Implementacion de referencia actual: [../langchain/README.md](../langchain/README.md)
310
+ - Documento de diseno: [../../docs/F2-04-Semantic-Kernel-Integration-Design.md](../../docs/F2-04-Semantic-Kernel-Integration-Design.md)
311
+ - Documentacion oficial: https://github.com/microsoft/semantic-kernel