agent-did-langchain 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_langchain-1.0.0rc1/PKG-INFO +492 -0
- agent_did_langchain-1.0.0rc1/README.md +462 -0
- agent_did_langchain-1.0.0rc1/pyproject.toml +67 -0
- agent_did_langchain-1.0.0rc1/setup.cfg +4 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain/__init__.py +40 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain/config.py +30 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain/context.py +44 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain/integration.py +103 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain/observability.py +395 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain/snapshot.py +52 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain/tools.py +522 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain.egg-info/PKG-INFO +492 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain.egg-info/SOURCES.txt +21 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain.egg-info/dependency_links.txt +1 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain.egg-info/requires.txt +11 -0
- agent_did_langchain-1.0.0rc1/src/agent_did_langchain.egg-info/top_level.txt +1 -0
- agent_did_langchain-1.0.0rc1/tests/test_context.py +40 -0
- agent_did_langchain-1.0.0rc1/tests/test_did_wba_demo.py +144 -0
- agent_did_langchain-1.0.0rc1/tests/test_integration.py +64 -0
- agent_did_langchain-1.0.0rc1/tests/test_observability.py +291 -0
- agent_did_langchain-1.0.0rc1/tests/test_security.py +123 -0
- agent_did_langchain-1.0.0rc1/tests/test_snapshot.py +29 -0
- agent_did_langchain-1.0.0rc1/tests/test_tools.py +72 -0
|
@@ -0,0 +1,492 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: agent-did-langchain
|
|
3
|
+
Version: 1.0.0rc1
|
|
4
|
+
Summary: LangChain Python integration for Agent-DID identities, context injection and secure tool exposure.
|
|
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,langchain,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: langchain<1.3,>=1.2.13
|
|
22
|
+
Requires-Dist: langchain-core<1.3,>=1.2.20
|
|
23
|
+
Requires-Dist: pydantic>=2.0
|
|
24
|
+
Provides-Extra: dev
|
|
25
|
+
Requires-Dist: build>=1.2; extra == "dev"
|
|
26
|
+
Requires-Dist: pytest>=8.0; extra == "dev"
|
|
27
|
+
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
|
|
28
|
+
Requires-Dist: ruff>=0.4; extra == "dev"
|
|
29
|
+
Requires-Dist: mypy>=1.10; extra == "dev"
|
|
30
|
+
|
|
31
|
+
# agent-did-langchain
|
|
32
|
+
|
|
33
|
+
Integracion funcional de Agent-DID para LangChain Python 1.2.x.
|
|
34
|
+
|
|
35
|
+
Esta variante complementa la integracion ya implementada en TypeScript/JavaScript y reutiliza el SDK Python real de Agent-DID como backend para snapshot de identidad, resolucion, verificacion, firma HTTP opt-in y rotacion controlada de claves.
|
|
36
|
+
|
|
37
|
+
La matriz de parity entre ambas integraciones vive en `../../docs/F1-03-LangChain-TS-Python-Integration-Parity-Matrix.md`.
|
|
38
|
+
|
|
39
|
+
## Estado
|
|
40
|
+
|
|
41
|
+
- Estado actual: `functional-mvp`
|
|
42
|
+
- Lenguaje objetivo: Python
|
|
43
|
+
- Dependencia previa resuelta: SDK Python de Agent-DID (F2-01)
|
|
44
|
+
- Relacion con roadmap: complemento Python de la integracion LangChain ya entregada en JS
|
|
45
|
+
- Implementacion: funcional para fases base, operaciones opt-in y readiness de CI
|
|
46
|
+
|
|
47
|
+
El paquete ya expone una factory publica, helpers de contexto, tools reutilizables, rotacion de claves opt-in y validacion de objetivos HTTP con rechazo por defecto de esquemas inseguros y destinos privados/loopback.
|
|
48
|
+
|
|
49
|
+
Ahora tambien expone una capa ligera de observabilidad vendor-neutral basada en callbacks y/o logger, con redaccion por defecto de payloads, firmas, cuerpos HTTP y headers sensibles.
|
|
50
|
+
|
|
51
|
+
## Compatibilidad objetivo
|
|
52
|
+
|
|
53
|
+
- `agent-did-sdk ==1.0.0rc1`
|
|
54
|
+
- `langchain >=1.2.13,<1.3`
|
|
55
|
+
- `langchain-core >=1.2.20,<1.3`
|
|
56
|
+
- Python 3.10+
|
|
57
|
+
|
|
58
|
+
## Instalacion
|
|
59
|
+
|
|
60
|
+
Para el paquete publicado del release candidate, la ruta objetivo es:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
python -m pip install agent-did-sdk==1.0.0rc1 agent-did-langchain==1.0.0rc1
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
Mientras la publicacion del RC corre, la validacion canonica en el repo sigue siendo:
|
|
67
|
+
|
|
68
|
+
```bash
|
|
69
|
+
python -m pip install -e ../../sdk-python
|
|
70
|
+
python -m pip install -e .[dev]
|
|
71
|
+
```
|
|
72
|
+
|
|
73
|
+
## Uso rapido
|
|
74
|
+
|
|
75
|
+
```python
|
|
76
|
+
from agent_did_langchain import create_agent_did_langchain_integration
|
|
77
|
+
from agent_did_sdk import AgentIdentity, AgentIdentityConfig, CreateAgentParams
|
|
78
|
+
from langchain.agents import create_agent
|
|
79
|
+
|
|
80
|
+
identity = AgentIdentity(AgentIdentityConfig(signer_address="0x1234567890123456789012345678901234567890"))
|
|
81
|
+
runtime_identity = await identity.create(
|
|
82
|
+
CreateAgentParams(
|
|
83
|
+
name="research_assistant",
|
|
84
|
+
core_model="gpt-4.1-mini",
|
|
85
|
+
system_prompt="Eres un agente preciso y trazable.",
|
|
86
|
+
capabilities=["research:web", "report:write"],
|
|
87
|
+
)
|
|
88
|
+
)
|
|
89
|
+
|
|
90
|
+
integration = create_agent_did_langchain_integration(
|
|
91
|
+
agent_identity=identity,
|
|
92
|
+
runtime_identity=runtime_identity,
|
|
93
|
+
expose={"sign_http": True},
|
|
94
|
+
)
|
|
95
|
+
|
|
96
|
+
agent = create_agent(
|
|
97
|
+
model="openai:gpt-4.1-mini",
|
|
98
|
+
tools=integration.tools,
|
|
99
|
+
system_prompt=integration.compose_system_prompt("Usa herramientas cuando aporten evidencia verificable."),
|
|
100
|
+
)
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
## Observabilidad
|
|
104
|
+
|
|
105
|
+
La factory publica acepta instrumentacion opcional sin acoplar el paquete a un backend especifico:
|
|
106
|
+
|
|
107
|
+
```python
|
|
108
|
+
import logging
|
|
109
|
+
|
|
110
|
+
from agent_did_langchain import create_agent_did_langchain_integration
|
|
111
|
+
|
|
112
|
+
logger = logging.getLogger("agent_did_langchain")
|
|
113
|
+
events = []
|
|
114
|
+
|
|
115
|
+
integration = create_agent_did_langchain_integration(
|
|
116
|
+
agent_identity=agent_identity,
|
|
117
|
+
runtime_identity=runtime_identity,
|
|
118
|
+
expose={"sign_http": True, "sign_payload": True},
|
|
119
|
+
observability_handler=events.append,
|
|
120
|
+
logger=logger,
|
|
121
|
+
)
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
Eventos emitidos:
|
|
125
|
+
|
|
126
|
+
- `agent_did.identity_snapshot.refreshed`
|
|
127
|
+
- `agent_did.tool.started`
|
|
128
|
+
- `agent_did.tool.succeeded`
|
|
129
|
+
- `agent_did.tool.failed`
|
|
130
|
+
|
|
131
|
+
Redaccion por defecto:
|
|
132
|
+
|
|
133
|
+
- `payload`, `body`, `signature` y `agent_private_key` se sustituyen por metadatos de longitud.
|
|
134
|
+
- `Authorization`, `Signature`, `Signature-Input`, `Cookie`, `Set-Cookie` y `X-API-Key` se redactan en headers.
|
|
135
|
+
- las URLs en eventos se normalizan sin query string, fragmento ni credenciales embebidas.
|
|
136
|
+
|
|
137
|
+
Esto permite conectar LangSmith, logging estructurado, trazas locales o callbacks propios sin exponer material sensible por defecto.
|
|
138
|
+
|
|
139
|
+
Si quiere reutilizar adaptadores listos para usar sin cambiar la API base, el paquete ahora expone:
|
|
140
|
+
|
|
141
|
+
- `compose_event_handlers(...)`: combina varios sinks/callbacks en un solo `observability_handler`.
|
|
142
|
+
- `create_json_logger_event_handler(logger, ...)`: emite cada evento como un registro JSON saneado, apto para pipelines de logging estructurado.
|
|
143
|
+
- `create_langsmith_run_tree(...)`: crea un `RunTree` local con inputs saneados para usarlo como raiz de tracing.
|
|
144
|
+
- `create_langsmith_event_handler(run_tree, ...)`: proyecta eventos Agent-DID en child runs de LangSmith, sin cambiar la factory principal.
|
|
145
|
+
- `serialize_observability_event(...)`: convierte un evento en un diccionario serializable para integrarlo con otros sistemas.
|
|
146
|
+
|
|
147
|
+
Tambien puede componer varios destinos al mismo tiempo, por ejemplo callback local + JSON logging + LangSmith:
|
|
148
|
+
|
|
149
|
+
```python
|
|
150
|
+
from agent_did_langchain import create_agent_did_langchain_integration
|
|
151
|
+
from agent_did_langchain.observability import (
|
|
152
|
+
compose_event_handlers,
|
|
153
|
+
create_json_logger_event_handler,
|
|
154
|
+
create_langsmith_event_handler,
|
|
155
|
+
create_langsmith_run_tree,
|
|
156
|
+
)
|
|
157
|
+
|
|
158
|
+
root_run = create_langsmith_run_tree(name="agent_did_demo", inputs={"scenario": "fanout"})
|
|
159
|
+
|
|
160
|
+
observability_handler = compose_event_handlers(
|
|
161
|
+
local_events.append,
|
|
162
|
+
create_json_logger_event_handler(logger, extra_fields={"sink": "json"}),
|
|
163
|
+
create_langsmith_event_handler(root_run, extra_fields={"sink": "langsmith"}),
|
|
164
|
+
)
|
|
165
|
+
|
|
166
|
+
integration = create_agent_did_langchain_integration(
|
|
167
|
+
agent_identity=agent_identity,
|
|
168
|
+
runtime_identity=runtime_identity,
|
|
169
|
+
observability_handler=observability_handler,
|
|
170
|
+
)
|
|
171
|
+
```
|
|
172
|
+
|
|
173
|
+
Ejemplo de logging JSON estructurado:
|
|
174
|
+
|
|
175
|
+
```python
|
|
176
|
+
import logging
|
|
177
|
+
|
|
178
|
+
from agent_did_langchain import create_agent_did_langchain_integration
|
|
179
|
+
from agent_did_langchain.observability import create_json_logger_event_handler
|
|
180
|
+
|
|
181
|
+
logger = logging.getLogger("agent_did_langchain.json")
|
|
182
|
+
|
|
183
|
+
integration = create_agent_did_langchain_integration(
|
|
184
|
+
agent_identity=agent_identity,
|
|
185
|
+
runtime_identity=runtime_identity,
|
|
186
|
+
expose={"sign_http": True},
|
|
187
|
+
observability_handler=create_json_logger_event_handler(
|
|
188
|
+
logger,
|
|
189
|
+
extra_fields={"service": "agent-gateway", "environment": "dev"},
|
|
190
|
+
),
|
|
191
|
+
)
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
Ejemplo de LangSmith sin cambiar la API base:
|
|
195
|
+
|
|
196
|
+
```python
|
|
197
|
+
from agent_did_langchain import create_agent_did_langchain_integration
|
|
198
|
+
from agent_did_langchain.observability import create_langsmith_event_handler, create_langsmith_run_tree
|
|
199
|
+
|
|
200
|
+
root_run = create_langsmith_run_tree(name="agent_did_demo", inputs={"scenario": "local"})
|
|
201
|
+
|
|
202
|
+
integration = create_agent_did_langchain_integration(
|
|
203
|
+
agent_identity=agent_identity,
|
|
204
|
+
runtime_identity=runtime_identity,
|
|
205
|
+
expose={"sign_http": True, "sign_payload": True},
|
|
206
|
+
observability_handler=create_langsmith_event_handler(root_run),
|
|
207
|
+
)
|
|
208
|
+
```
|
|
209
|
+
|
|
210
|
+
## Recetas operativas
|
|
211
|
+
|
|
212
|
+
### Receta 1: callback local para debugging rapido
|
|
213
|
+
|
|
214
|
+
Use esta receta cuando quiera inspeccionar rapidamente el flujo de tools en desarrollo local o tests.
|
|
215
|
+
|
|
216
|
+
```python
|
|
217
|
+
events = []
|
|
218
|
+
|
|
219
|
+
integration = create_agent_did_langchain_integration(
|
|
220
|
+
agent_identity=agent_identity,
|
|
221
|
+
runtime_identity=runtime_identity,
|
|
222
|
+
observability_handler=lambda event: events.append(
|
|
223
|
+
{
|
|
224
|
+
"event_type": event.event_type,
|
|
225
|
+
"level": event.level,
|
|
226
|
+
"attributes": event.attributes,
|
|
227
|
+
}
|
|
228
|
+
),
|
|
229
|
+
)
|
|
230
|
+
```
|
|
231
|
+
|
|
232
|
+
Util para:
|
|
233
|
+
|
|
234
|
+
- inspeccionar `agent_did.tool.failed`
|
|
235
|
+
- validar que la redaccion de payloads y headers aplica correctamente
|
|
236
|
+
- correlacionar snapshots de identidad con llamadas de tools
|
|
237
|
+
|
|
238
|
+
### Receta 2: logging JSON estructurado para agregacion
|
|
239
|
+
|
|
240
|
+
Use esta receta cuando quiera enviar observabilidad a archivos, stdout estructurado o pipelines centralizados.
|
|
241
|
+
|
|
242
|
+
```python
|
|
243
|
+
import logging
|
|
244
|
+
|
|
245
|
+
from agent_did_langchain.observability import create_json_logger_event_handler
|
|
246
|
+
|
|
247
|
+
logger = logging.getLogger("agent_did_langchain")
|
|
248
|
+
logger.setLevel(logging.INFO)
|
|
249
|
+
|
|
250
|
+
integration = create_agent_did_langchain_integration(
|
|
251
|
+
agent_identity=agent_identity,
|
|
252
|
+
runtime_identity=runtime_identity,
|
|
253
|
+
observability_handler=create_json_logger_event_handler(
|
|
254
|
+
logger,
|
|
255
|
+
extra_fields={"service": "agent-gateway", "environment": "prod"},
|
|
256
|
+
),
|
|
257
|
+
)
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
Use esta salida cuando necesite:
|
|
261
|
+
|
|
262
|
+
- enviar eventos a collectors sin parsear texto libre
|
|
263
|
+
- correlacionar eventos por `service`, `environment` o metadata propia
|
|
264
|
+
- mantener saneamiento de secretos antes del borde de logging
|
|
265
|
+
|
|
266
|
+
### Receta 3: LangSmith para tracing de tools
|
|
267
|
+
|
|
268
|
+
Use esta receta cuando quiera conservar la API publica del paquete y proyectar los eventos Agent-DID como child runs en LangSmith.
|
|
269
|
+
|
|
270
|
+
```python
|
|
271
|
+
from agent_did_langchain.observability import create_langsmith_event_handler, create_langsmith_run_tree
|
|
272
|
+
|
|
273
|
+
root_run = create_langsmith_run_tree(
|
|
274
|
+
name="agent_did_production_session",
|
|
275
|
+
project_name="agent-did-langchain",
|
|
276
|
+
inputs={"scenario": "tool-tracing"},
|
|
277
|
+
tags=["agent-did", "production"],
|
|
278
|
+
)
|
|
279
|
+
|
|
280
|
+
integration = create_agent_did_langchain_integration(
|
|
281
|
+
agent_identity=agent_identity,
|
|
282
|
+
runtime_identity=runtime_identity,
|
|
283
|
+
observability_handler=create_langsmith_event_handler(root_run),
|
|
284
|
+
)
|
|
285
|
+
```
|
|
286
|
+
|
|
287
|
+
Use LangSmith cuando necesite:
|
|
288
|
+
|
|
289
|
+
- seguir tool runs individuales con contexto saneado
|
|
290
|
+
- conservar el arbol de ejecucion para debugging de agentes
|
|
291
|
+
- auditar secuencias multi-tool sin leer secretos desde prompts u outputs
|
|
292
|
+
|
|
293
|
+
### Receta 4: fan-out a varios sinks
|
|
294
|
+
|
|
295
|
+
Use esta receta cuando necesite callback local, logging JSON y LangSmith al mismo tiempo.
|
|
296
|
+
|
|
297
|
+
```python
|
|
298
|
+
from agent_did_langchain.observability import (
|
|
299
|
+
compose_event_handlers,
|
|
300
|
+
create_json_logger_event_handler,
|
|
301
|
+
create_langsmith_event_handler,
|
|
302
|
+
create_langsmith_run_tree,
|
|
303
|
+
)
|
|
304
|
+
|
|
305
|
+
root_run = create_langsmith_run_tree(name="agent_did_fanout", inputs={"scenario": "fanout"})
|
|
306
|
+
|
|
307
|
+
observability_handler = compose_event_handlers(
|
|
308
|
+
local_events.append,
|
|
309
|
+
create_json_logger_event_handler(logger, extra_fields={"sink": "json"}),
|
|
310
|
+
create_langsmith_event_handler(root_run, extra_fields={"sink": "langsmith"}),
|
|
311
|
+
)
|
|
312
|
+
```
|
|
313
|
+
|
|
314
|
+
Esta es la receta recomendada cuando quiera:
|
|
315
|
+
|
|
316
|
+
- debugging local y trazabilidad remota en paralelo
|
|
317
|
+
- mantener un sink humano y otro estructurado simultaneamente
|
|
318
|
+
- desacoplar la observabilidad del backend final
|
|
319
|
+
|
|
320
|
+
## Ejemplo orientado a produccion
|
|
321
|
+
|
|
322
|
+
El paquete incluye un ejemplo opt-in mas cercano a un despliegue real en:
|
|
323
|
+
|
|
324
|
+
- `examples/agent_did_langchain_production_recipe_example.py`
|
|
325
|
+
|
|
326
|
+
Ese ejemplo muestra:
|
|
327
|
+
|
|
328
|
+
- configuracion por variables de entorno
|
|
329
|
+
- uso de `create_agent(...)` con modelo real
|
|
330
|
+
- observabilidad compuesta con callback local, JSON logging y LangSmith opcional
|
|
331
|
+
- guardas para evitar ejecucion accidental sin credenciales o flags explicitos
|
|
332
|
+
|
|
333
|
+
Variables principales:
|
|
334
|
+
|
|
335
|
+
- `RUN_LANGCHAIN_PRODUCTION_EXAMPLE=1`: habilita la ejecucion real del agente
|
|
336
|
+
- `LANGCHAIN_MODEL`: modelo/provider para `create_agent(...)`, por ejemplo `openai:gpt-4.1-mini`
|
|
337
|
+
- `AGENT_DID_SIGNER_ADDRESS`: signer address del runtime local
|
|
338
|
+
- `OPENAI_API_KEY`: requerida si usa un modelo OpenAI real
|
|
339
|
+
- `LANGSMITH_TRACING=1`: habilita fan-out adicional a LangSmith si el entorno ya esta configurado
|
|
340
|
+
|
|
341
|
+
Si faltan credenciales o la flag de ejecucion, el ejemplo termina sin error y solo imprime instrucciones.
|
|
342
|
+
|
|
343
|
+
## Hallazgos tecnicos confirmados
|
|
344
|
+
|
|
345
|
+
La documentacion publica actual de LangChain Python confirma al menos estas superficies utiles:
|
|
346
|
+
|
|
347
|
+
- `create_agent(...)` como factory principal para agentes.
|
|
348
|
+
- `tools` como mecanismo nativo para exponer funciones al agente.
|
|
349
|
+
- `system_prompt` y `messages` como puntos base para inyectar identidad y contexto.
|
|
350
|
+
- `agent.invoke(...)` como interfaz directa de ejecucion.
|
|
351
|
+
- runtime construido sobre LangGraph, con soporte de durabilidad, streaming, human-in-the-loop y persistence en el ecosistema.
|
|
352
|
+
- LangSmith como camino recomendado para tracing y observabilidad.
|
|
353
|
+
|
|
354
|
+
## Que agrega la integracion
|
|
355
|
+
|
|
356
|
+
- Snapshot estable de identidad Agent-DID sin secretos.
|
|
357
|
+
- Composicion de `system_prompt` con DID, controlador, capacidades y reglas operativas.
|
|
358
|
+
- Tools para identidad actual, resolucion DID y verificacion de firmas.
|
|
359
|
+
- Tools opt-in para firma HTTP, firma de payload, historial documental y rotacion de claves.
|
|
360
|
+
|
|
361
|
+
## Objetivo arquitectonico
|
|
362
|
+
|
|
363
|
+
Mantener en Python el enfoque ya validado en JS:
|
|
364
|
+
|
|
365
|
+
- inyectar DID, controlador, capacidades y metadata verificable en el contexto del agente,
|
|
366
|
+
- exponer herramientas Agent-DID para resolucion, verificacion y firma opt-in,
|
|
367
|
+
- mantener la clave privada fuera del prompt y del estado visible al modelo,
|
|
368
|
+
- ofrecer una API de integracion pequena y consistente entre lenguajes.
|
|
369
|
+
|
|
370
|
+
## API publica del MVP
|
|
371
|
+
|
|
372
|
+
```python
|
|
373
|
+
from agent_did_langchain import create_agent_did_langchain_integration
|
|
374
|
+
|
|
375
|
+
integration = create_agent_did_langchain_integration(
|
|
376
|
+
agent_identity=agent_identity,
|
|
377
|
+
runtime_identity=runtime_identity,
|
|
378
|
+
expose={
|
|
379
|
+
"verify_signatures": True,
|
|
380
|
+
"sign_http": True,
|
|
381
|
+
"rotate_keys": False,
|
|
382
|
+
},
|
|
383
|
+
)
|
|
384
|
+
```
|
|
385
|
+
|
|
386
|
+
El objeto devuelto expone:
|
|
387
|
+
|
|
388
|
+
- `tools`
|
|
389
|
+
- `identity_snapshot`
|
|
390
|
+
- `get_current_identity()`
|
|
391
|
+
- `get_current_document()`
|
|
392
|
+
- `compose_system_prompt(base_prompt, additional_context=None)`
|
|
393
|
+
|
|
394
|
+
## Checklist operativo
|
|
395
|
+
|
|
396
|
+
La ejecucion del scaffold a paquete funcional esta desglosada en [../../docs/F1-03-LangChain-Python-Implementation-Checklist.md](../../docs/F1-03-LangChain-Python-Implementation-Checklist.md).
|
|
397
|
+
|
|
398
|
+
El plan tecnico cerrado por archivos, versiones objetivo y criterios de aceptacion esta en [../../docs/F1-03-LangChain-Python-Technical-Plan.md](../../docs/F1-03-LangChain-Python-Technical-Plan.md).
|
|
399
|
+
|
|
400
|
+
## Componentes principales
|
|
401
|
+
|
|
402
|
+
- `pyproject.toml`: metadata del paquete Python.
|
|
403
|
+
- `src/agent_did_langchain/__init__.py`: factory principal y exports publicos.
|
|
404
|
+
- `src/agent_did_langchain/config.py`: configuracion y defaults de exposicion.
|
|
405
|
+
- `src/agent_did_langchain/snapshot.py`: snapshot serializable de identidad.
|
|
406
|
+
- `src/agent_did_langchain/context.py`: composicion de prompt/contexto.
|
|
407
|
+
- `src/agent_did_langchain/tools.py`: herramientas Agent-DID para LangChain Python.
|
|
408
|
+
- `src/agent_did_langchain/integration.py`: ensamblaje publico del adaptador.
|
|
409
|
+
- `src/agent_did_langchain/observability.py`: eventos, redaccion y hooks de observabilidad.
|
|
410
|
+
- `tests/`: pruebas funcionales y de seguridad.
|
|
411
|
+
- `examples/agent_did_langchain_example.py`: quick start runnable.
|
|
412
|
+
- `examples/agent_did_langchain_did_wba_demo.py`: demo integrado con runtime `did:wba`, resolucion web y firma HTTP verificable.
|
|
413
|
+
- `examples/agent_did_langchain_observability_example.py`: callback tracing y redaccion segura.
|
|
414
|
+
- `examples/agent_did_langchain_secure_http_example.py`: firma HTTP verificable end-to-end.
|
|
415
|
+
- `examples/agent_did_langchain_langsmith_example.py`: tracing local sobre `RunTree` de LangSmith con child runs saneados.
|
|
416
|
+
- `examples/agent_did_langchain_multitool_agent_example.py`: flujo `create_agent(...)` con fake chat model y varias tools Agent-DID.
|
|
417
|
+
- `examples/agent_did_langchain_composed_observability_example.py`: fan-out simultaneo a callback local, JSON logging y LangSmith.
|
|
418
|
+
- `examples/agent_did_langchain_production_recipe_example.py`: ejemplo opt-in con variables de entorno, modelo real y observabilidad compuesta.
|
|
419
|
+
|
|
420
|
+
## Criterios de implementacion
|
|
421
|
+
|
|
422
|
+
1. Exponer DID actual, resolucion documental y verificacion de firmas mediante tools.
|
|
423
|
+
2. Permitir firma HTTP solo con opt-in explicito.
|
|
424
|
+
3. Mantener rotacion de claves deshabilitada por defecto y fuera de este MVP.
|
|
425
|
+
4. Inyectar identidad Agent-DID en el contexto del agente sin exponer secretos.
|
|
426
|
+
5. Incluir ejemplos runnable y pruebas automatizadas en Python.
|
|
427
|
+
|
|
428
|
+
## Seguridad operativa
|
|
429
|
+
|
|
430
|
+
- `sign_http` solo existe con opt-in.
|
|
431
|
+
- `sign_payload` solo existe con opt-in.
|
|
432
|
+
- `rotate_keys` solo existe con opt-in.
|
|
433
|
+
- Los secretos nunca se devuelven en outputs de tools.
|
|
434
|
+
- La observabilidad redacta payloads, firmas, cuerpos HTTP y headers sensibles por defecto.
|
|
435
|
+
- La firma HTTP rechaza por defecto `file://`, URLs con credenciales embebidas y destinos `localhost` o redes privadas.
|
|
436
|
+
- Si el caso de uso requiere firmar hacia targets internos controlados, puede habilitarse `allow_private_network_targets=True` en la factory.
|
|
437
|
+
|
|
438
|
+
## Ejemplos disponibles
|
|
439
|
+
|
|
440
|
+
- `examples/agent_did_langchain_example.py`: ensamblaje base, tool calls directos y opcion de demo con modelo real usando `RUN_LANGCHAIN_MODEL_EXAMPLE=1`.
|
|
441
|
+
- `examples/agent_did_langchain_did_wba_demo.py`: demo integrado sin dependencias externas con identidad activa `did:wba`, partner remoto `did:wba`, `create_agent(...)` local y verificacion de firma HTTP.
|
|
442
|
+
- `examples/agent_did_langchain_observability_example.py`: muestra eventos estructurados y la redaccion aplicada a inputs sensibles.
|
|
443
|
+
- `examples/agent_did_langchain_secure_http_example.py`: firma HTTP, devuelve headers verificables y valida la firma con el SDK Python.
|
|
444
|
+
- `examples/agent_did_langchain_json_logging_example.py`: emite eventos saneados como logs JSON listos para agregacion.
|
|
445
|
+
- `examples/agent_did_langchain_langsmith_example.py`: convierte eventos Agent-DID en child runs de LangSmith sin requerir cambios en la factory.
|
|
446
|
+
- `examples/agent_did_langchain_multitool_agent_example.py`: ejecuta `create_agent(...)` localmente con un fake chat model y muestra un recorrido multi-tool reproducible.
|
|
447
|
+
- `examples/agent_did_langchain_composed_observability_example.py`: demuestra composicion de handlers para emitir simultaneamente a tres sinks.
|
|
448
|
+
- `examples/agent_did_langchain_production_recipe_example.py`: receta opt-in para entorno real con guardas de credenciales, modelo configurable y fan-out de observabilidad.
|
|
449
|
+
|
|
450
|
+
## Demo integrado `did:wba`
|
|
451
|
+
|
|
452
|
+
Para ejecutar el demo integrado local de LangChain Python sin depender de credenciales externas:
|
|
453
|
+
|
|
454
|
+
```bash
|
|
455
|
+
cd integrations/langchain-python
|
|
456
|
+
python examples/agent_did_langchain_did_wba_demo.py
|
|
457
|
+
```
|
|
458
|
+
|
|
459
|
+
Este demo prueba en un solo flujo:
|
|
460
|
+
|
|
461
|
+
- identidad activa `did:wba`
|
|
462
|
+
- resolucion de una contraparte remota `did:wba`
|
|
463
|
+
- `create_agent(...)` con fake chat model reproducible
|
|
464
|
+
- firma HTTP Agent-DID verificable end-to-end
|
|
465
|
+
|
|
466
|
+
La cobertura automatizada equivalente vive en:
|
|
467
|
+
|
|
468
|
+
- `tests/test_did_wba_demo.py`
|
|
469
|
+
|
|
470
|
+
## Troubleshooting rapido
|
|
471
|
+
|
|
472
|
+
- Si una tool devuelve `error`, revise el evento `agent_did.tool.failed` para ver el contexto ya redactado.
|
|
473
|
+
- Si necesita correlacion entre prompt y snapshot de identidad, observe `agent_did.identity_snapshot.refreshed`.
|
|
474
|
+
- Si `sign_http_request` falla con targets locales, confirme si debe habilitar explicitamente `allow_private_network_targets=True`.
|
|
475
|
+
- Si usa LangSmith, cree un `RunTree` local y conectelo mediante `create_langsmith_event_handler(...)`.
|
|
476
|
+
- Si usa un backend externo de observabilidad, conectelo mediante `observability_handler` o `logger` en lugar de leer secretos desde outputs de tools.
|
|
477
|
+
|
|
478
|
+
## Validacion local recomendada
|
|
479
|
+
|
|
480
|
+
```bash
|
|
481
|
+
cd ../..
|
|
482
|
+
npm run langchain-python:install-dev
|
|
483
|
+
npm run lint:langchain-python
|
|
484
|
+
npm run typecheck:langchain-python
|
|
485
|
+
npm run test:langchain-python
|
|
486
|
+
```
|
|
487
|
+
|
|
488
|
+
## Referencias
|
|
489
|
+
|
|
490
|
+
- Integracion JS funcional: [../langchain/README.md](../langchain/README.md)
|
|
491
|
+
- Documento de diseno: [../../docs/F1-03-LangChain-Python-Integration-Design.md](../../docs/F1-03-LangChain-Python-Integration-Design.md)
|
|
492
|
+
- Documentacion oficial: https://docs.langchain.com/oss/python/langchain/overview
|