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.
- agent_did_semantic_kernel-1.0.0rc1/PKG-INFO +346 -0
- agent_did_semantic_kernel-1.0.0rc1/README.md +311 -0
- agent_did_semantic_kernel-1.0.0rc1/pyproject.toml +75 -0
- agent_did_semantic_kernel-1.0.0rc1/setup.cfg +4 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/__init__.py +49 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/config.py +30 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/context.py +42 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/integration.py +148 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/observability.py +340 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/runtime.py +87 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/sanitization.py +101 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/snapshot.py +52 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel/tools.py +530 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel.egg-info/PKG-INFO +346 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel.egg-info/SOURCES.txt +21 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel.egg-info/dependency_links.txt +1 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel.egg-info/requires.txt +18 -0
- agent_did_semantic_kernel-1.0.0rc1/src/agent_did_semantic_kernel.egg-info/top_level.txt +1 -0
- agent_did_semantic_kernel-1.0.0rc1/tests/test_context.py +35 -0
- agent_did_semantic_kernel-1.0.0rc1/tests/test_integration.py +71 -0
- agent_did_semantic_kernel-1.0.0rc1/tests/test_observability.py +203 -0
- agent_did_semantic_kernel-1.0.0rc1/tests/test_runtime_smoke.py +160 -0
- 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
|