1. Primera ejecución
En un entorno de Python 3.14 o posterior, instala el núcleo. Añade los adaptadores que necesites con la misma versión.
python -m pip install agnara==1.0.4
El ejemplo declara una suma con permiso obligatorio y salida entera. Compila su plan una vez, construye un contexto por llamada y cierra el contenedor al terminar. La identidad se construye localmente para el ejemplo. En un servicio real el host la obtiene de su autenticación.
import asyncio
from agnara import Agnara, Principal
from agnara.di import DIContainer, DIRegistry
from agnara.execution import (
ExecutionContext, ExecutionPlan, Failure, FailureCode,
Invocation, Success, invoke_result,
)
async def main():
app = Agnara("calculator")
@app.capability(scopes={"calculator:use"}, output=int)
def add(a: int, b: int) -> int:
return a + b
registry = DIRegistry()
plan = ExecutionPlan.compile(app.compile()["calculator.add"], registry)
container = DIContainer(registry)
actor = Principal("demo", scopes={"calculator:use"})
async def call(a, principal):
invocation = Invocation(plan.definition.id, {"a": a, "b": 3}, {})
context = ExecutionContext(invocation, container, principal=principal)
return await invoke_result(plan, context)
try:
ok = await call(2, actor)
denied = await call(2, Principal("guest"))
malformed = await call(True, actor)
assert isinstance(ok, Success) and ok.value == 5
assert isinstance(denied, Failure) and denied.code is FailureCode.FORBIDDEN
assert isinstance(malformed, Failure)
assert malformed.code is FailureCode.INVALID_INPUT
print(ok.value, denied.code.value, malformed.code.value)
finally:
await container.aclose()
asyncio.run(main())
Resultado verificado 5 forbidden invalid_input. La segunda llamada carece del permiso requerido. La tercera aporta un booleano donde el contrato exige un entero.
Para componer HTTP, declara una ruta con Http y los argumentos con Binding. Para MCP, publica la misma capacidad con Mcp.tool y construye el servidor con build_mcp_server.
2. Aplicación y capacidades
agnara · 41 exportaciones
Declara la operación de negocio una vez. La aplicación y sus contextos organizan el registro. Las políticas y los esquemas describen qué puede ejecutarse y qué datos admite cada operación.
Guía relacionada · AGENT_GUIDE.md
Agnara · AgnaraError · AnonymousPrincipal · App · AppDescriptor · CapabilityDefinition · CapabilityId · CapabilityRegistry · Confirmation · ConfirmationEvidence · ConfirmationVerdict · ConfirmationVerifier · DefinitionError · DuplicateAppError · DuplicateCapabilityError · FrozenCapabilityRegistry · Idempotency · InteractionKind · InteractionRequest · InteractionRequiredError · InvocationError · JsonSchema · Policy · PolicyDeniedError · PolicyFailure · PolicyInteractionRequired · PolicyResult · PolicySuccess · Principal · RegistryError · RegistryFrozenError · Risk · SchemaAdapter · SchemaError · ScopePolicy · StandardEffect · StandardSchemaAdapter · TypeSchema · UnknownCapabilityError · ValidationError · __version__
Agnara
Clase · Estable · agnara
Punto de entrada de una aplicación. Registra capacidades propias, monta contextos con include() y congela la colección con compile(). Su nombre funciona como espacio de nombres de las capacidades que declara directamente.
Agnara(name: str) -> None
Parámetros
name- Nombre lógico de la entidad que se declara, describe o publica.
Importa Agnara para el proyecto y App para un contexto delimitado. El registro es mutable durante el arranque. La compilación cierra la declaración de capacidades.
Agnara.name Propiedad
Nombre de la aplicación y espacio de nombres de sus capacidades directas. str
Agnara.capabilities Propiedad
Accede al registro de capacidades declaradas. CapabilityRegistry
Agnara.is_compiled Propiedad
Indica que se cerró el registro. bool
Agnara.capability Método
capability(
handler: Any = None,
/,
*,
name: str | None = None,
description: str | None = None,
scopes: Iterable[str] = (),
effects: Iterable[str] = (),
risk: Risk | str = Risk.LOW,
confirmation: Confirmation | str = Confirmation.NEVER,
idempotent: bool | None = None,
streaming: bool = False,
output: object = typing.Any,
) -> AnyRegistra una función como capacidad, con decorador directo o parametrizado. Conserva la función para usarla como referencia al componer exposiciones.
handler- Función Python que ejecuta la operación.
name- Nombre lógico de la entidad que se declara, describe o publica.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
scopes- Permisos declarados por la capacidad o concedidos a una identidad verificada.
effects- Conjunto de etiquetas que describe los efectos de la capacidad.
risk- Clasificación del impacto potencial de una invocación incorrecta.
confirmation- Régimen de confirmación declarado para la capacidad.
idempotent- Atajo de declaración para indicar si es seguro repetir la operación.
streaming- Indica que la capacidad produce unidades mediante un stream.
output- Anotación explícita del contrato de salida.
Agnara.include Método
include(app: App) -> App
Monta las capacidades de un contexto y comprueba colisiones antes de incorporarlo.
app- Aplicación o contexto que posee las declaraciones.
Agnara.apps Propiedad
Devuelve los contextos montados en orden de inclusión. Mapping[str, App]
Agnara.compile Método
compile() -> FrozenCapabilityRegistry
Cierra el registro y devuelve una vista inmutable. Los planes se compilan en un paso separado.
AgnaraError
Excepción · Estable · agnara
Excepción base de Agnara. Permite capturar fallos del framework en un límite de aplicación.
AnonymousPrincipal
Clase · Estable · agnara
Identidad anónima sin permisos concedidos. Sirve para representar una invocación sin autenticar.
AnonymousPrincipal(metadata: collections.abc.Mapping[str, Any] | None = None) -> None
Parámetros
metadata- Datos auxiliares de contexto. No son una credencial ni conceden permisos.
Atributos
identity: str- Identificador estable de la persona o servicio, o identidad verificada entregada al mapeador.
metadata: dict[str, typing.Any]- Datos auxiliares de contexto. No son una credencial ni conceden permisos.
scopes: frozenset[str]- Permisos declarados por la capacidad o concedidos a una identidad verificada.
App
Clase · Estable · agnara
Contexto delimitado que agrupa capacidades relacionadas. Puede montarse en una aplicación Agnara conservando su propio espacio de nombres.
App(name: str, *, description: str | None = None, module: str | None = None) -> None
Parámetros
name- Nombre lógico de la entidad que se declara, describe o publica.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
module- Nombre de módulo de procedencia que puede aparecer en el descriptor.
App.descriptor Propiedad
Devuelve los metadatos de identidad del contexto. AppDescriptor
App.name Propiedad
Nombre del contexto y espacio de nombres de las capacidades propias. str
App.capabilities Propiedad
Devuelve el registro de capacidades declaradas en el contexto. CapabilityRegistry
App.capability Método
capability(
handler: Any = None,
/,
*,
name: str | None = None,
description: str | None = None,
scopes: Iterable[str] = (),
effects: Iterable[str] = (),
risk: Risk | str = Risk.LOW,
confirmation: Confirmation | str = Confirmation.NEVER,
idempotent: bool | None = None,
streaming: bool = False,
output: object = typing.Any,
) -> AnyRegistra una función como capacidad de este contexto.
handler- Función Python que ejecuta la operación.
name- Nombre lógico de la entidad que se declara, describe o publica.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
scopes- Permisos declarados por la capacidad o concedidos a una identidad verificada.
effects- Conjunto de etiquetas que describe los efectos de la capacidad.
risk- Clasificación del impacto potencial de una invocación incorrecta.
confirmation- Régimen de confirmación declarado para la capacidad.
idempotent- Atajo de declaración para indicar si es seguro repetir la operación.
streaming- Indica que la capacidad produce unidades mediante un stream.
output- Anotación explícita del contrato de salida.
AppDescriptor
Clase · Estable · agnara
Metadatos de identidad de un contexto delimitado para composición e introspección.
AppDescriptor(
name: str,
description: str | None = None,
module: str | None = None,
) -> NoneParámetros
name- Nombre lógico de la entidad que se declara, describe o publica.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
module- Nombre de módulo de procedencia que puede aparecer en el descriptor.
Atributos
name: str- Nombre lógico de la entidad que se declara, describe o publica.
description: str | None- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
module: str | None- Nombre de módulo de procedencia que puede aparecer en el descriptor.
CapabilityDefinition
Clase · Estable · agnara
Declaración de una capacidad independiente del transporte. Reúne la función, su contrato de salida, sus políticas y sus metadatos. Normalmente se obtiene al registrar una función.
CapabilityDefinition(
id: CapabilityId,
handler: Handler,
description: str | None = None,
effects: frozenset[str] = <factory>,
scopes: frozenset[str] = <factory>,
risk: Risk = Risk.LOW,
confirmation: Confirmation = Confirmation.NEVER,
idempotency: Idempotency = Idempotency.UNKNOWN,
policies: tuple[Policy, ...] = <factory>,
streaming: bool = False,
output: object = typing.Any,
) -> NoneParámetros
id- Identificador del registro. Su tipo depende de la entidad.
handler- Función Python que ejecuta la operación.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
effects- Conjunto de etiquetas que describe los efectos de la capacidad.
scopes- Permisos declarados por la capacidad o concedidos a una identidad verificada.
risk- Clasificación del impacto potencial de una invocación incorrecta.
confirmation- Régimen de confirmación declarado para la capacidad.
idempotency- Metadato de repetición segura o configuración explícita de reserva, según el tipo indicado.
policies- Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
streaming- Indica que la capacidad produce unidades mediante un stream.
output- Anotación explícita de salida. El plan la compila al construir el contrato.
Un identificador inválido, una declaración incompatible o metadatos mal formados pueden producir DefinitionError durante la construcción.
Atributos
id: CapabilityId- Identificador del registro. Su tipo depende de la entidad.
handler: Handler- Función Python que ejecuta la operación.
description: str | None- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
effects: frozenset[str]- Conjunto de etiquetas que describe los efectos de la capacidad.
scopes: frozenset[str]- Permisos declarados por la capacidad o concedidos a una identidad verificada.
risk: Risk- Clasificación del impacto potencial de una invocación incorrecta.
confirmation: Confirmation- Régimen de confirmación declarado para la capacidad.
idempotency: Idempotency- Metadato de repetición segura o configuración explícita de reserva, según el tipo indicado.
policies: tuple[Policy, ...]- Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
streaming: bool- Indica que la capacidad produce unidades mediante un stream.
output: object- Anotación explícita de salida. El plan la compila al construir el contrato.
CapabilityDefinition.declare Método
declare(
*,
id: CapabilityId,
handler: Handler,
description: str | None = None,
scopes: Iterable[str] = (),
effects: Iterable[str] = (),
risk: Risk | str = Risk.LOW,
confirmation: Confirmation | str = Confirmation.NEVER,
idempotency: Idempotency | str = Idempotency.UNKNOWN,
policies: Iterable[Policy] = (),
streaming: bool = False,
output: object = typing.Any,
) -> SelfConstruye una declaración validada a partir de los metadatos de autoría.
id- Identificador del registro. Su tipo depende de la entidad.
handler- Función Python que ejecuta la operación.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
scopes- Permisos declarados por la capacidad o concedidos a una identidad verificada.
effects- Conjunto de etiquetas que describe los efectos de la capacidad.
risk- Clasificación del impacto potencial de una invocación incorrecta.
confirmation- Régimen de confirmación declarado para la capacidad.
idempotency- Metadato de repetición segura o configuración explícita de reserva, según el tipo indicado.
policies- Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
streaming- Indica que la capacidad produce unidades mediante un stream.
output- Anotación explícita del contrato de salida.
CapabilityDefinition.has_effect Método
has_effect(effect: str) -> bool
Comprueba si se declaró la etiqueta de efecto solicitada.
effect- Etiqueta de efecto que se comprueba o utiliza como filtro.
CapabilityDefinition.requires_scope Método
requires_scope(scope: str) -> bool
Comprueba si la capacidad declara ese permiso como requerido.
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
CapabilityId
Clase · Estable · agnara
Identificador lógico de una capacidad. La forma textual separa el espacio de nombres y el nombre con un punto.
CapabilityId(namespace: str, name: str) -> None
Parámetros
namespace- Espacio de nombres al que pertenece la capacidad.
name- Nombre lógico de la entidad que se declara, describe o publica.
Usa CapabilityId.parse("catalog.total") al recibir una identidad textual. Las invocaciones reciben el objeto CapabilityId.
Atributos
namespace: str- Espacio de nombres al que pertenece la capacidad.
name: str- Nombre lógico de la entidad que se declara, describe o publica.
CapabilityId.parse Método
parse(text: str) -> CapabilityId
Convierte un identificador textual con punto en un CapabilityId.
text- Identificador textual que se convierte a su forma estructurada.
CapabilityRegistry
Clase · Estable · agnara
Registro mutable durante el arranque. Detecta duplicados y se cierra con freeze().
CapabilityRegistry(definitions: Iterable[CapabilityDefinition] = ()) -> None
Parámetros
definitions- Declaraciones de capacidad con las que se inicializa el registro.
CapabilityRegistry.is_frozen Propiedad
Indica si se cerraron las declaraciones. bool
CapabilityRegistry.register Método
register(definition: CapabilityDefinition) -> CapabilityDefinition
Registra y devuelve una definición. Detecta identificadores duplicados.
definition- Declaración de la capacidad que se compila o expone.
CapabilityRegistry.freeze Método
freeze() -> FrozenCapabilityRegistry
Cierra el registro y devuelve su vista inmutable.
CapabilityRegistry.__getitem__ Método
__getitem__(key: CapabilityKey) -> CapabilityDefinition
Busca un elemento por su clave.
key- Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.
CapabilityRegistry.__contains__ Método
__contains__(key: object) -> bool
Comprueba si la clave pertenece a la colección.
key- Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.
CapabilityRegistry.__iter__ Método
__iter__() -> Iterator[CapabilityId]
Recorre las claves de la colección.
CapabilityRegistry.__len__ Método
__len__() -> int
Devuelve la cantidad de declaraciones o elementos de la colección.
Confirmation
Enumeración · Estable · agnara
Indica el régimen de confirmación humana de una capacidad. La evidencia debe pasar por un verificador configurado.
NEVER = 'never'- El régimen de la capacidad no exige confirmación.
POLICY = 'policy'- Una política decide si la invocación concreta requiere confirmación.
REQUIRED = 'required'- La capacidad exige confirmación verificada.
ConfirmationEvidence
Clase · Estable · agnara
Contenedor de evidencia opaca suministrada por un límite de confianza. El contenido requiere verificación antes de conceder una confirmación.
ConfirmationEvidence(value: object) -> None
Parámetros
value- Contenido opaco que interpreta el verificador de la aplicación.
Atributos
value: object- Contenido opaco que interpreta el verificador de la aplicación.
ConfirmationVerdict
Enumeración · Estable · agnara
Decisión que devuelve un verificador sobre la evidencia presentada para una invocación.
VALID = 'valid'- El verificador aceptó la evidencia para esta invocación.
INVALID = 'invalid'- El verificador rechazó la evidencia.
ConfirmationVerifier
Protocolo · Estable · agnara
Protocolo que implementa la aplicación para comprobar evidencia vinculada a una capacidad, invocación e identidad concretas.
ConfirmationVerifier.verify Método
async verify(
evidence: ConfirmationEvidence,
*,
capability_id: CapabilityId,
invocation: Invocation,
principal: Principal,
) -> ConfirmationVerdictComprueba evidencia para la capacidad, solicitud e identidad indicadas y devuelve un ConfirmationVerdict.
evidence- Evidencia opaca que el verificador comprueba para esta solicitud.
capability_id- Identificador lógico de la capacidad.
invocation- Solicitud de ejecución que contiene identidad de capacidad y entrada.
principal- Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.
DefinitionError
Excepción · Estable · agnara
Una declaración de capacidad es inválida para el runtime.
DuplicateAppError
Excepción · Estable · agnara
Dos contextos montados reclaman la misma identidad.
DuplicateCapabilityError
Excepción · Estable · agnara
Dos declaraciones reclaman el mismo identificador de capacidad.
FrozenCapabilityRegistry
Clase · Estable · agnara
Vista inmutable de las capacidades registradas. Permite buscar por identificador y consultar subconjuntos por espacio de nombres o efecto.
FrozenCapabilityRegistry(
definitions: Mapping[CapabilityId, CapabilityDefinition],
) -> NoneParámetros
definitions- Declaraciones de capacidad con las que se inicializa el registro.
FrozenCapabilityRegistry.__getitem__ Método
__getitem__(key: CapabilityKey) -> CapabilityDefinition
Busca un elemento por su clave.
key- Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.
FrozenCapabilityRegistry.__contains__ Método
__contains__(key: object) -> bool
Comprueba si la clave pertenece a la colección.
key- Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.
FrozenCapabilityRegistry.__iter__ Método
__iter__() -> Iterator[CapabilityId]
Recorre las claves de la colección.
FrozenCapabilityRegistry.__len__ Método
__len__() -> int
Devuelve la cantidad de declaraciones o elementos de la colección.
FrozenCapabilityRegistry.namespaces Propiedad
Devuelve los espacios de nombres con capacidades registradas. frozenset[str]
FrozenCapabilityRegistry.in_namespace Método
in_namespace(namespace: str) -> tuple[CapabilityDefinition, ...]
Devuelve las capacidades del espacio de nombres en orden de registro.
namespace- Espacio de nombres al que pertenece la capacidad.
FrozenCapabilityRegistry.with_effect Método
with_effect(effect: str) -> tuple[CapabilityDefinition, ...]
Devuelve las capacidades que declaran el efecto solicitado, en orden de registro.
effect- Etiqueta de efecto que se comprueba o utiliza como filtro.
Idempotency
Enumeración · Estable · agnara
Describe si una capacidad admite repetición segura. El metadato por sí solo no reserva una ejecución ni guarda su resultado.
YES = 'yes'- La capacidad declara que la repetición es segura.
NO = 'no'- La capacidad declara que repetirla puede duplicar efectos.
UNKNOWN = 'unknown'- La declaración no establece seguridad de repetición.
InteractionKind
Enumeración · Estable · agnara
Vocabulario de interacciones que pueden ser necesarias antes de continuar.
CONFIRMATION = 'confirmation'- Se requiere confirmación del llamador.
InteractionRequest
Clase · Estable · agnara
Información apta para mostrar al llamador cuando se requiere una interacción previa a la ejecución.
InteractionRequest(
kind: InteractionKind,
title: str,
message: str,
capability_id: CapabilityId,
hints: Mapping[str, InteractionHint] = <factory>,
) -> NoneParámetros
kind- Categoría de interacción, proveedor o descriptor según el tipo indicado.
title- Título que puede mostrarse al lector.
message- Mensaje de fallo o interacción que el llamador puede leer.
capability_id- Identificador lógico de la capacidad.
hints- Información estructurada apta para orientar al llamador.
Atributos
kind: InteractionKind- Categoría de interacción, proveedor o descriptor según el tipo indicado.
title: str- Título que puede mostrarse al lector.
message: str- Mensaje de fallo o interacción que el llamador puede leer.
capability_id: CapabilityId- Identificador lógico de la capacidad.
hints: Mapping[str, InteractionHint]- Información estructurada apta para orientar al llamador.
InteractionRequiredError
Excepción · Estable · agnara
Interrumpe una invocación directa cuando se necesita una interacción con el llamador. Su solicitud describe el siguiente paso.
InteractionRequiredError(request: InteractionRequest) -> None
Parámetros
request- Solicitud de interacción que explica al llamador cómo continuar.
Atributos
request: InteractionRequest- Solicitud de interacción que explica al llamador cómo continuar.
InvocationError
Excepción · Estable · agnara
Una invocación directa es incoherente con el plan o el contexto que recibe el runtime.
JsonSchema
Alias de tipo · Estable · agnara
Alias para una representación de JSON Schema como mapeo de claves de texto.
JsonSchema = collections.abc.Mapping[str, typing.Any]
Policy
Protocolo · Estable · agnara
Protocolo de una regla evaluada antes del handler. Recibe el contexto y devuelve un PolicyResult.
Policy.evaluate Método
async evaluate(context: ExecutionContext) -> PolicyResult
Evalúa el contexto antes del handler y devuelve una autorización, denegación o solicitud de interacción.
context- Contexto de la invocación que se va a evaluar o ejecutar.
PolicyDeniedError
Excepción · Estable · agnara
Una política previa al handler denegó la invocación directa.
PolicyFailure
Clase · Estable · agnara
Resultado de política que deniega la operación.
PolicyFailure(reason: str) -> None
Parámetros
reason- Motivo seguro que acompaña a la denegación.
Atributos
reason: str- Motivo seguro que acompaña a la denegación.
PolicyInteractionRequired
Clase · Estable · agnara
Resultado de política que detiene la ejecución hasta que el llamador complete una interacción.
PolicyInteractionRequired(request: InteractionRequest) -> None
Parámetros
request- Solicitud de interacción que explica al llamador cómo continuar.
Atributos
request: InteractionRequest- Solicitud de interacción que explica al llamador cómo continuar.
PolicyResult
Alias de tipo · Estable · agnara
Unión de los resultados posibles de una política. Distingue autorización, denegación y necesidad de interacción.
PolicyResult = PolicySuccess | PolicyFailure | PolicyInteractionRequired
PolicySuccess
Clase · Estable · agnara
Resultado de política que permite continuar con la ejecución.
PolicySuccess() -> None
Principal
Clase · Estable · agnara
Identidad autenticada y permisos otorgados por el host. Los datos enviados en el payload no son una fuente de identidad.
Principal(
identity: str,
metadata: collections.abc.Mapping[str, Any] | None = None,
scopes: collections.abc.Iterable[str] = (),
) -> NoneParámetros
identity- Identificador estable de la persona o servicio, o identidad verificada entregada al mapeador.
metadata- Datos auxiliares de contexto. No son una credencial ni conceden permisos.
scopes- Permisos declarados por la capacidad o concedidos a una identidad verificada.
Atributos
identity: str- Identificador estable de la persona o servicio, o identidad verificada entregada al mapeador.
metadata: dict[str, typing.Any]- Datos auxiliares de contexto. No son una credencial ni conceden permisos.
scopes: frozenset[str]- Permisos declarados por la capacidad o concedidos a una identidad verificada.
RegistryError
Excepción · Estable · agnara
Uso incompatible con el contrato del registro de capacidades.
RegistryFrozenError
Excepción · Estable · agnara
Se intentó modificar un registro que ya está congelado.
Risk
Enumeración · Estable · agnara
Clasifica el daño potencial de una invocación errónea o maliciosa. Es metadato y la autorización depende de las políticas.
LOW = 'low'- Impacto bajo.
MEDIUM = 'medium'- Impacto medio.
HIGH = 'high'- Impacto alto.
CRITICAL = 'critical'- Impacto crítico.
SchemaAdapter
Protocolo · Estable · agnara
Protocolo que transforma una anotación de Python en un esquema reutilizable.
SchemaAdapter.compile Método
compile(annotation: Any) -> TypeSchema
Prepara un esquema reutilizable para la anotación o informa un SchemaError.
annotation- Anotación de tipo Python que se describe o compila.
SchemaAdapter.supports Método
supports(annotation: Any) -> bool
Indica si puede compilar esa anotación.
annotation- Anotación de tipo Python que se describe o compila.
SchemaError
Excepción · Estable · agnara
Una anotación no se pudo compilar como esquema.
ScopePolicy
Clase · Estable · agnara
Exige que la identidad activa tenga todos los permisos indicados por la regla.
ScopePolicy(required_scopes: Iterable[str] = ()) -> None
Parámetros
required_scopes- Permisos que la regla exige en conjunto.
Atributos
required_scopes: frozenset[str]- Permisos que la regla exige en conjunto.
ScopePolicy.evaluate Método
async evaluate(context: ExecutionContext) -> PolicyResult
Autoriza cuando la identidad activa posee todos los permisos que exige la regla.
context- Contexto de la invocación que se va a evaluar o ejecutar.
StandardEffect
Enumeración · Estable · agnara
Vocabulario de etiquetas para describir lecturas, escrituras y efectos destructivos.
NONE = 'none'- Sin efectos declarados.
READ = 'read'- Lectura.
CACHE_WRITE = 'cache-write'- Escritura en caché.
DATABASE_WRITE = 'database-write'- Escritura en base de datos.
EXTERNAL_WRITE = 'external-write'- Escritura en un sistema externo.
FINANCIAL_WRITE = 'financial-write'- Operación con efecto financiero.
DESTRUCTIVE = 'destructive'- Efecto destructivo.
StandardSchemaAdapter
Clase · Estable · agnara
Compila anotaciones comunes con la biblioteca estándar, incluidos tipos simples, contenedores, uniones, enumeraciones y dataclasses compatibles.
StandardSchemaAdapter() -> None
StandardSchemaAdapter.compile Método
compile(annotation: Any) -> TypeSchema
Compila la anotación con los tipos admitidos por el adaptador de biblioteca estándar.
annotation- Anotación de tipo Python que se describe o compila.
StandardSchemaAdapter.supports Método
supports(annotation: Any) -> bool
Comprueba si el adaptador estándar puede compilar la anotación.
annotation- Anotación de tipo Python que se describe o compila.
TypeSchema
Protocolo · Estable · agnara
Protocolo de un esquema compilado. Valida valores de Python y emite una representación JSON Schema.
TypeSchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
TypeSchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
UnknownCapabilityError
Excepción · Estable · agnara
El identificador solicitado no existe en el registro.
ValidationError
Excepción · Estable · agnara
Un valor incumple el contrato de su esquema. La ruta permite ubicar el campo o elemento afectado.
ValidationError(message: str, *, path: tuple[str | int, ...] = ()) -> None
Parámetros
message- Mensaje de fallo o interacción que el llamador puede leer.
path- Tupla de campos e índices que localiza el dato inválido. La raíz es la tupla vacía.
Atributos
message: str- Mensaje de fallo o interacción que el llamador puede leer.
path: tuple[str | int, ...]- Tupla de campos e índices que localiza el dato inválido. La raíz es la tupla vacía.
ValidationError.at Método
at(segment: str | int) -> ValidationError
Devuelve un nuevo error con un segmento adicional al principio de la ruta.
segment- Campo o índice que se antepone a la ruta del error.
ValidationError.location Propiedad
Representa la ruta de error para lectura humana. En la raíz usa <value>. str
__version__
Constante · Estable · agnara
Versión del paquete principal importado en este proceso.
__version__ = '1.0.4'
3. Inyección de dependencias
agnara.di · 9 exportaciones
Asocia cada tipo a un proveedor antes de compilar. Los recursos de invocación terminan con la llamada. Los singleton se cierran con su contenedor, en el bucle que los posee.
Guía relacionada · DEPENDENCIES.md
DIContainer · DIRegistry · DependencyCycleError · DependencyResolutionError · ProviderDefinition · ProviderType · Scope · compile_dag · provider
DIContainer
Clase · Estable · agnara.di
Resuelve dependencias y conserva los recursos singleton. Su propietario debe cerrarlo con aclose() en el bucle que lo usa.
DIContainer(registry: DIRegistry) -> None
Parámetros
registry- Registro de capacidades o asociaciones de DI del que parte la operación.
Scope.INVOCATION se libera con cada invocación. Scope.SINGLETON se libera con aclose(). Los proveedores que entregan recursos con yield deben liberar en finally.
Atributos
registry: DIRegistry- Registro de capacidades o asociaciones de DI del que parte la operación.
singleton_cache: dict[type, Any]- Caché de dependencias singleton que administra el contenedor. Trátala como estado del contenedor.
exit_stack- Pila de cierre que administra el contenedor. Cierra los recursos mediante aclose().
DIContainer.aclose Método
async aclose() -> None
Cierra los recursos singleton que posee el contenedor.
DIContainer.resolve_dependencies Método
resolve_dependencies(
target_func: collections.abc.Callable[..., typing.Any],
target_deps: collections.abc.Mapping[collections.abc.Callable[..., typing.Any], collections.abc.Sequence[type]],
) -> collections.abc.AsyncGenerator[dict[str, typing.Any]]Resuelve los argumentos de dependencia de la función usando el grafo precompilado.
target_func- Función objetivo para la cual se resuelven dependencias.
target_deps- Mapa de dependencias del objetivo generado al compilar el grafo.
DIRegistry
Clase · Estable · agnara.di
Tabla de asociaciones explícitas entre tipos solicitados y proveedores. Se prepara antes de compilar los planes.
DIRegistry() -> None
DIRegistry.bind Método
bind(
provides: type,
provider: ProviderDefinition | collections.abc.Callable[..., Any],
) -> NoneAsocia explícitamente un tipo a la declaración del proveedor que lo suministra.
provides- Tipo que suministra la asociación.
provider- Declaración de proveedor que se asocia al tipo.
DIRegistry.get_provider Método
get_provider(provides: type) -> ProviderDefinition | None
Obtiene el proveedor asociado al tipo.
provides- Tipo que suministra la asociación.
DIRegistry.is_bound Método
is_bound(provides: type) -> bool
Comprueba si existe una asociación para el tipo solicitado.
provides- Tipo que suministra la asociación.
DIRegistry.all_bindings Método
all_bindings() -> dict[type, ProviderDefinition]
Devuelve las asociaciones registradas.
DependencyCycleError
Excepción · Estable · agnara.di
El grafo de proveedores contiene un ciclo.
DependencyResolutionError
Excepción · Estable · agnara.di
Una dependencia no pudo resolverse para la ejecución solicitada.
ProviderDefinition
Clase · Estable · agnara.di
Descripción de un proveedor, de su tipo de callable y de la duración del recurso que entrega.
ProviderDefinition(
func: collections.abc.Callable[..., typing.Any],
scope: Scope,
provider_type: ProviderType,
return_type: type,
) -> NoneParámetros
func- Función o generador que proporciona la dependencia.
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
provider_type- Clase de callable del proveedor, según ProviderType.
return_type- Tipo que declara producir el proveedor.
Atributos
func: collections.abc.Callable[..., typing.Any]- Función o generador que proporciona la dependencia.
scope: Scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
provider_type: ProviderType- Clase de callable del proveedor, según ProviderType.
return_type: type- Tipo que declara producir el proveedor.
ProviderDefinition.from_callable Método
from_callable(
func: collections.abc.Callable[..., typing.Any],
scope: Scope,
) -> ProviderDefinitionConstruye la declaración e identifica la forma del callable y el tipo de retorno.
func- Función o generador que proporciona la dependencia.
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
ProviderType
Enumeración · Estable · agnara.di
Clasifica el proveedor según la forma en que produce el valor. El contenedor usa esa forma para adquirirlo y liberar sus recursos.
SYNC_FUNCTION = 'sync_function'- La función síncrona devuelve el recurso.
ASYNC_FUNCTION = 'async_function'- Se espera a la función asíncrona para obtener el recurso.
SYNC_GENERATOR = 'sync_generator'- El generador síncrono entrega un recurso y permite su liberación al cerrarlo.
ASYNC_GENERATOR = 'async_generator'- El generador asíncrono entrega un recurso y permite su liberación asíncrona.
Scope
Enumeración · Estable · agnara.di
Duración del valor que devuelve un proveedor.
SINGLETON = 'singleton'- Se reutiliza durante la vida del contenedor.
INVOCATION = 'invocation'- Se adquiere y libera con la invocación.
compile_dag
Función · Estable · agnara.di
Compila el grafo de dependencias de las funciones objetivo. Detecta ciclos y prepara la resolución antes de invocar.
compile_dag(
registry: DIRegistry,
target_funcs: list[collections.abc.Callable[..., typing.Any]],
) -> dict[collections.abc.Callable[..., typing.Any], list[type]]Parámetros
registry- Registro de capacidades o asociaciones de DI del que parte la operación.
target_funcs- Funciones raíz cuyos proveedores se compilan.
provider
Función · Estable · agnara.di
Decorador que declara una función o generador como proveedor. Asocia el resultado a un tipo con DIRegistry.bind().
provider(
*,
scope: Scope = Scope.INVOCATION,
) -> collections.abc.Callable[[collections.abc.Callable[..., typing.Any]], ProviderDefinition]Parámetros
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
4. Ejecución de capacidades
agnara.execution · 32 exportaciones
El plan prepara el trabajo de arranque. Cada llamada crea su propio contexto. Las políticas preceden a la materialización, validación y adquisición de recursos. El plazo usa un reloj monotónico y la cancelación del llamador se propaga.
Guía relacionada · DIRECT_IDEMPOTENCY.md
CanonicalResult · CapabilityInvoker · CapabilityRuntime · CapabilityStream · ExecutionContext · ExecutionPlan · Failure · FailureCode · IdempotencyClaimed · IdempotencyCompleted · IdempotencyConflict · IdempotencyConflictError · IdempotencyInProgress · IdempotencyInProgressError · IdempotencyInvocation · IdempotencyReservation · IdempotencyResultCodec · IdempotencyScope · IdempotencyStorageError · IdempotencyStore · InMemoryIdempotencyStore · Invocation · InvocationStartEvent · InvocationTerminalEvent · StreamInterrupted · StreamTerminal · Success · TelemetryHook · classify_failure · invoke · invoke_result · open_stream
CanonicalResult
Alias de tipo · Estable · agnara.execution
Resultado transportable de una invocación completa. Puede contener un éxito con valor o un fallo con categoría segura.
CanonicalResult = Success[T] | Failure
CapabilityInvoker
Clase · Estable · agnara.execution
Dependencia inyectada que permite invocar otra capacidad de resultado completo en la misma aplicación. La invocación hija vuelve a pasar por políticas.
Inyecta este tipo en el handler cuando uses CapabilityRuntime. Cada llamada hija pasa por el plan compilado.
CapabilityInvoker.invoke Método
async invoke(
capability_id: CapabilityId,
payload: Mapping[str, Any],
*,
timeout: float | None = None,
) -> CanonicalResult[Any]Invoca una capacidad del mismo runtime como hija, con su propio contexto y evaluación de políticas.
capability_id- Identificador lógico de la capacidad.
payload- Datos de entrada suministrados para la invocación o bytes opacos que recibe el códec.
timeout- Presupuesto de ejecución en segundos. None omite este límite explícito.
CapabilityRuntime
Clase · Estable · agnara.execution
Runtime de una aplicación compilada. Selecciona el plan desde la identidad de la invocación y gestiona composición anidada.
CapabilityRuntime(
capabilities: FrozenCapabilityRegistry,
plans: Sequence[ExecutionPlan],
container: DIContainer,
*,
max_composition_depth: int = 8,
) -> NoneParámetros
capabilities- Conjunto de capacidades declaradas o compiladas que delimita la composición.
plans- Planes compilados que la superficie puede despachar o describir.
container- Contenedor de dependencias de la aplicación.
max_composition_depth- Profundidad máxima de invocaciones anidadas permitida.
El hijo vuelve a autorizarse con la identidad derivada del padre. La composición es dentro de la misma aplicación y comparte el presupuesto de tiempo según el contrato de ejecución anidada.
CapabilityRuntime.invoke Método
async invoke(context: ExecutionContext) -> Any
Selecciona el plan según el contexto y ejecuta con excepciones de Python.
context- Contexto de la invocación que se va a evaluar o ejecutar.
CapabilityRuntime.invoke_result Método
async invoke_result(
context: ExecutionContext,
*,
input_materializer: Callable[[TypeSchema, object], object] | None = None,
) -> CanonicalResult[T]Selecciona el plan y devuelve un resultado canónico.
context- Contexto de la invocación que se va a evaluar o ejecutar.
input_materializer- Conversión de datos del límite de transporte a valores de entrada Python.
CapabilityRuntime.aclose Método
async aclose() -> None
Cierra el contenedor de dependencias de la aplicación.
CapabilityStream
Clase · Estable · agnara.execution
Consumo asíncrono de un stream de una sola ejecución. Entrega unidades bajo demanda y expone cómo terminó.
CapabilityStream.units_emitted Propiedad
Número de unidades que ya recibió este consumidor. int
CapabilityStream.terminal Propiedad
Estado terminal del stream o None mientras siga activo. StreamTerminal | None
CapabilityStream.execution_id Propiedad
Identidad lógica de esta ejecución de streaming. str
CapabilityStream.__aiter__ Método
__aiter__() -> AsyncIterator[Any]
Entrega el iterador asíncrono de esta ejecución para async for.
CapabilityStream.__anext__ Método
async __anext__() -> Any
Solicita una unidad, sujeta al plazo de la invocación.
CapabilityStream.aclose Método
async aclose() -> None
Cierra el productor y libera los recursos del alcance de la invocación.
ExecutionContext
Clase · Estable · agnara.execution
Entorno de una invocación. Vincula entrada, contenedor e identidad verificada y expone el plazo e identidad de ejecución.
ExecutionContext(
invocation: Invocation,
di_container: DIContainer,
tracking_id: str | None = None,
principal: Principal | None = None,
confirmation_evidence: ConfirmationEvidence | None = None,
idempotency: IdempotencyInvocation | None = None,
) -> NoneParámetros
invocation- Solicitud de ejecución que contiene identidad de capacidad y entrada.
di_container- Contenedor que aporta los recursos de esta ejecución.
tracking_id- Etiqueta opcional de correlación externa. No concede autoridad.
principal- Identidad verificada. Queda fija durante la ejecución y el valor por omisión es anónimo.
confirmation_evidence- Evidencia opaca para esta invocación. Queda fija al construir el contexto.
idempotency- Configuración explícita de idempotencia fijada al construir el contexto.
Crea un contexto por llamada. Calcula un plazo de 30 segundos con asyncio.get_running_loop().time() + 30. La cancelación es cooperativa y las funciones síncronas pueden bloquear el bucle.
Atributos
invocation: Invocation- Solicitud de ejecución que contiene identidad de capacidad y entrada.
di_container: DIContainer- Contenedor que aporta los recursos de esta ejecución.
tracking_id: str | None- Etiqueta opcional de correlación externa. No concede autoridad.
state: dict[str, Any]- Diccionario mutable para datos de esta ejecución. Tiene alcance local a la invocación.
ExecutionContext.principal Propiedad
Identidad verificada. Queda fija durante la ejecución y el valor por omisión es anónimo. Principal
ExecutionContext.confirmation_evidence Propiedad
Evidencia opaca para esta invocación. Queda fija al construir el contexto. ConfirmationEvidence | None
ExecutionContext.idempotency Propiedad
Configuración explícita de idempotencia fijada al construir el contexto. IdempotencyInvocation | None
ExecutionContext.execution_id Propiedad
Identidad lógica opaca asignada por el runtime. Es independiente de tracking_id. str
ExecutionContext.deadline Propiedad
Plazo monotónico absoluto de la invocación, si se configuró. float | None
ExecutionContext.remaining_time Método
remaining_time(now: float | None = None) -> float | None
Calcula los segundos restantes, con mínimo cero. Devuelve None sin plazo.
now- Lectura monotónica usada para calcular el tiempo restante.
ExecutionPlan
Clase · Estable · agnara.execution
Plan inmutable que conecta una capacidad con esquemas, políticas, dependencias y hooks. Usa compile() como punto de composición.
Los parámetros protegidos los aporta el runtime. Un payload que intenta rellenarlos no puede sustituir una dependencia o el contexto.
Atributos
definition: CapabilityDefinition- Declaración de la capacidad que se compila o expone.
target_deps: Mapping[Callable[..., Any], Sequence[type]]- Mapa de dependencias del objetivo generado al compilar el grafo.
hooks: tuple[TelemetryHook, ...]- Observadores de telemetría del plan o de la superficie.
policies: tuple[Policy, ...]- Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
dependency_parameters: frozenset[str]- Nombres de parámetros vinculados a proveedores.
context_parameters: tuple[str, ...]- Parámetros del handler reservados para el contexto de ejecución.
capability_invoker_parameters: tuple[str, ...]- Parámetros de la función reservados para el invocador de capacidades.
protected_parameters: frozenset[str]- Parámetros que aporta el runtime y que el llamador no puede rellenar.
input_schemas: Mapping[str, TypeSchema]- Mapeo de parámetros de entrada a esquemas compilados.
required_inputs: frozenset[str]- Entradas que debe aportar el llamador.
output_schema: TypeSchema- Esquema compilado que valida el valor producido.
ExecutionPlan.compile Método
compile(
definition: CapabilityDefinition,
registry: DIRegistry,
hooks: Sequence[TelemetryHook] = (),
confirmation_verifier: ConfirmationVerifier | None = None,
schema_adapter: SchemaAdapter | None = None,
) -> ExecutionPlanValida la declaración, clasifica los parámetros, compila los esquemas y resuelve el grafo de proveedores antes de invocar.
definition- Declaración de la capacidad que se compila o expone.
registry- Registro de capacidades o asociaciones de DI del que parte la operación.
hooks- Observadores de telemetría del plan o de la superficie.
confirmation_verifier- Verificador que la aplicación suministra al compilar.
schema_adapter- Adaptador que compila anotaciones en esquemas.
ExecutionPlan.dependencies Propiedad
Tipos de las dependencias directas en el orden de la firma del handler. tuple[type, ...]
ExecutionPlan.streaming Propiedad
Indica que este plan se consume mediante open_stream(). bool
Failure
Clase · Estable · agnara.execution
Fallo canónico con código, mensaje apto para el llamador y detalles inmutables. Los adaptadores lo proyectan a su protocolo.
Failure(
code: FailureCode,
message: str,
details: Mapping[str, FailureDetail] = <factory>,
execution_id: str | None = None,
) -> NoneParámetros
code- Categoría semántica del fallo.
message- Mensaje de fallo o interacción que el llamador puede leer.
details- Pares clave y valor aptos para publicar junto al fallo.
execution_id- Identidad lógica opaca que asigna o recupera el runtime.
Atributos
code: FailureCode- Categoría semántica del fallo.
message: str- Mensaje de fallo o interacción que el llamador puede leer.
details: Mapping[str, FailureDetail]- Pares clave y valor aptos para publicar junto al fallo.
execution_id: str | None- Identidad lógica opaca que asigna o recupera el runtime.
FailureCode
Enumeración · Estable · agnara.execution
Categorías semánticas de fallo compartidas por los transportes.
INVALID_INPUT = 'invalid_input'- La entrada incumple el contrato.
UNAUTHENTICATED = 'unauthenticated'- Se necesita autenticación.
FORBIDDEN = 'forbidden'- La identidad carece de autoridad.
NOT_FOUND = 'not_found'- No se encontró el recurso o destino.
CONFLICT = 'conflict'- La solicitud entra en conflicto con el estado actual.
RATE_LIMITED = 'rate_limited'- Se alcanzó un límite de solicitudes.
INTERACTION_REQUIRED = 'interaction_required'- Hace falta una interacción con el llamador.
UNAVAILABLE = 'unavailable'- La operación está temporalmente indisponible.
TIMEOUT = 'timeout'- Se agotó el plazo de ejecución.
INTERNAL_FAILURE = 'internal_failure'- Se produjo un fallo interno con diagnóstico público redactado.
IdempotencyClaimed
Clase · Estable · agnara.execution
El llamador obtuvo la reserva atómica para ejecutar una operación.
IdempotencyClaimed(reservation: IdempotencyReservation) -> None
Parámetros
reservation- Reserva opaca que prueba que un intento puede completar o abandonar el selector.
Atributos
reservation: IdempotencyReservation- Reserva opaca que prueba que un intento puede completar o abandonar el selector.
IdempotencyCompleted
Clase · Estable · agnara.execution
El almacén contiene un éxito reutilizable para el selector y huella coincidentes.
IdempotencyCompleted(execution_id: str, result: bytes) -> None
Parámetros
execution_id- Identidad lógica opaca que asigna o recupera el runtime.
result- Bytes opacos del éxito previamente almacenado.
Atributos
execution_id: str- Identidad lógica opaca que asigna o recupera el runtime.
result: bytes- Bytes opacos del éxito previamente almacenado.
IdempotencyConflict
Clase · Estable · agnara.execution
La misma clave se presentó con una huella de solicitud distinta.
IdempotencyConflict() -> None
IdempotencyConflictError
Excepción · Estable · agnara.execution
El selector no puede aplicarse a la invocación lógica actual.
IdempotencyInProgress
Clase · Estable · agnara.execution
La operación coincidente sigue reservada por otra invocación.
IdempotencyInProgress(execution_id: str) -> None
Parámetros
execution_id- Identidad lógica opaca que asigna o recupera el runtime.
Atributos
execution_id: str- Identidad lógica opaca que asigna o recupera el runtime.
IdempotencyInProgressError
Excepción · Estable · agnara.execution
Otra invocación posee la reserva del selector coincidente.
IdempotencyInvocation
Clase · Estable · agnara.execution
Activa la idempotencia explícita de una invocación de resultado completo con selector, almacén, códec y duraciones.
IdempotencyInvocation(
scope: IdempotencyScope,
store: IdempotencyStore,
codec: IdempotencyResultCodec,
lease_ttl: float,
result_ttl: float,
) -> NoneParámetros
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
store- Almacén que arbitra reservas y éxitos de idempotencia.
codec- Códec de éxitos configurado para almacenamiento.
lease_ttl- Tiempo en segundos durante el cual la reserva conserva la propiedad.
result_ttl- Tiempo en segundos de conservación del éxito.
Configura la huella y clave en el límite de confianza. El runtime comprueba autoridad antes de reutilizar un éxito. El almacén de referencia no conserva datos al reiniciar.
Atributos
scope: IdempotencyScope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
store: IdempotencyStore- Almacén que arbitra reservas y éxitos de idempotencia.
codec: IdempotencyResultCodec- Códec de éxitos configurado para almacenamiento.
lease_ttl: float- Tiempo en segundos durante el cual la reserva conserva la propiedad.
result_ttl: float- Tiempo en segundos de conservación del éxito.
IdempotencyReservation
Clase · Estable · agnara.execution
Credencial opaca de una reserva aceptada. El almacén la comprueba para completar o abandonar el intento.
IdempotencyReservation(scope: IdempotencyScope, execution_id: str, token: str) -> None
Parámetros
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
execution_id- Identidad lógica opaca que asigna o recupera el runtime.
token- Valor opaco del almacén que distingue esta reserva de las demás.
Atributos
scope: IdempotencyScope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
execution_id: str- Identidad lógica opaca que asigna o recupera el runtime.
token: str- Valor opaco del almacén que distingue esta reserva de las demás.
IdempotencyResultCodec
Protocolo · Estable · agnara.execution
Protocolo para convertir éxitos a bytes acotados y reconstruirlos. El códec pertenece a la aplicación.
IdempotencyResultCodec.encode Método
encode(value: object, /) -> bytes
Convierte un valor satisfactorio en bytes acotados para almacenarlo.
value- Valor que se valida, contiene o transforma.
IdempotencyResultCodec.decode Método
decode(payload: bytes, /) -> object
Reconstruye el valor de éxito desde los bytes guardados.
payload- Datos de entrada suministrados para la invocación o bytes opacos que recibe el códec.
IdempotencyScope
Clase · Estable · agnara.execution
Identidad compuesta de la solicitud para idempotencia. Vincula capacidad, identidad, clave y huella.
IdempotencyScope(
capability_id: CapabilityId,
principal_id: str,
key: str,
fingerprint: bytes,
) -> NoneParámetros
capability_id- Identificador lógico de la capacidad.
principal_id- Identidad estable asociada al selector de idempotencia.
key- Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.
fingerprint- Huella del contenido lógico de la solicitud que calcula la aplicación.
Atributos
capability_id: CapabilityId- Identificador lógico de la capacidad.
principal_id: str- Identidad estable asociada al selector de idempotencia.
key: str- Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.
fingerprint: bytes- Huella del contenido lógico de la solicitud que calcula la aplicación.
IdempotencyStorageError
Excepción · Estable · agnara.execution
El almacén configurado no puede realizar la operación de idempotencia de forma segura.
IdempotencyStore
Protocolo · Estable · agnara.execution
Protocolo de almacenamiento que coordina reservas y conserva éxitos mediante operaciones atómicas.
Las reservas caducan. El almacén compara la reserva al completar o abandonar para proteger a un propietario nuevo de un intento anterior.
IdempotencyStore.claim Método
async claim(
scope: IdempotencyScope,
*,
lease_ttl: float,
) -> IdempotencyClaimed | IdempotencyInProgress | IdempotencyCompleted | IdempotencyConflictReserva atómicamente el selector o devuelve el estado que ya tiene.
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
lease_ttl- Tiempo en segundos durante el cual la reserva conserva la propiedad.
IdempotencyStore.lookup Método
async lookup(
scope: IdempotencyScope,
) -> IdempotencyInProgress | IdempotencyCompleted | IdempotencyConflict | NoneConsulta el estado sin adquirir una reserva.
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
IdempotencyStore.complete Método
async complete(
reservation: IdempotencyReservation,
result: bytes,
*,
result_ttl: float,
) -> boolPublica atómicamente un éxito si la reserva aún pertenece al intento.
reservation- Reserva opaca que prueba que un intento puede completar o abandonar el selector.
result- Valor o bytes del resultado según el contrato del método.
result_ttl- Tiempo en segundos de conservación del éxito.
IdempotencyStore.abandon Método
async abandon(reservation: IdempotencyReservation) -> bool
Libera una reserva vigente tras fallo o cancelación.
reservation- Reserva opaca que prueba que un intento puede completar o abandonar el selector.
InMemoryIdempotencyStore
Clase · Estable · agnara.execution
Almacén de referencia con capacidad acotada dentro de un proceso. Sus registros desaparecen al reiniciar.
InMemoryIdempotencyStore(
*,
max_entries: int = 1024,
clock: Callable[[], float] = monotonic,
) -> NoneParámetros
max_entries- Cantidad máxima de registros que el almacén de referencia puede conservar.
clock- Función de reloj que devuelve segundos monotónicos.
InMemoryIdempotencyStore.claim Método
async claim(
scope: IdempotencyScope,
*,
lease_ttl: float,
) -> IdempotencyClaimed | IdempotencyInProgress | IdempotencyCompleted | IdempotencyConflictReserva atómicamente el selector o devuelve el estado que ya tiene.
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
lease_ttl- Tiempo en segundos durante el cual la reserva conserva la propiedad.
InMemoryIdempotencyStore.lookup Método
async lookup(
scope: IdempotencyScope,
) -> IdempotencyInProgress | IdempotencyCompleted | IdempotencyConflict | NoneConsulta el estado sin adquirir una reserva.
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
InMemoryIdempotencyStore.complete Método
async complete(
reservation: IdempotencyReservation,
result: bytes,
*,
result_ttl: float,
) -> boolPublica atómicamente un éxito si la reserva aún pertenece al intento.
reservation- Reserva opaca que prueba que un intento puede completar o abandonar el selector.
result- Valor o bytes del resultado según el contrato del método.
result_ttl- Tiempo en segundos de conservación del éxito.
InMemoryIdempotencyStore.abandon Método
async abandon(reservation: IdempotencyReservation) -> bool
Libera una reserva vigente tras fallo o cancelación.
reservation- Reserva opaca que prueba que un intento puede completar o abandonar el selector.
Invocation
Clase · Estable · agnara.execution
Entrada aún sin validar de una ejecución, con identidad de capacidad, datos, metadatos y un plazo monotónico opcional.
Invocation(
capability_id: CapabilityId,
payload: dict[str, typing.Any],
metadata: dict[str, typing.Any],
deadline: float | None = None,
) -> NoneParámetros
capability_id- Identificador lógico de la capacidad.
payload- Datos de entrada suministrados para la invocación o bytes opacos que recibe el códec.
metadata- Datos auxiliares de la llamada. execution_id está reservado al runtime.
deadline- Instante absoluto en el reloj monotónico del bucle de ejecución.
Atributos
capability_id: CapabilityId- Identificador lógico de la capacidad.
payload: dict[str, typing.Any]- Datos de entrada suministrados para la invocación o bytes opacos que recibe el códec.
metadata: dict[str, typing.Any]- Datos auxiliares de la llamada. execution_id está reservado al runtime.
deadline: float | None- Instante absoluto en el reloj monotónico del bucle de ejecución.
InvocationStartEvent
Clase · Estable · agnara.execution
Evento de telemetría emitido al comenzar una invocación.
InvocationStartEvent(
capability_id: CapabilityId,
tracking_id: str | None,
invocation_id: str,
execution_id: str | None = None,
parent_execution_id: str | None = None,
) -> NoneParámetros
capability_id- Identificador lógico de la capacidad.
tracking_id- Etiqueta opcional de correlación externa. No concede autoridad.
invocation_id- Identificador del intento de invocación observado.
execution_id- Identidad lógica opaca que asigna o recupera el runtime.
parent_execution_id- Identidad lógica de la ejecución padre, si existe.
Atributos
capability_id: CapabilityId- Identificador lógico de la capacidad.
tracking_id: str | None- Etiqueta opcional de correlación externa. No concede autoridad.
invocation_id: str- Identificador del intento de invocación observado.
execution_id: str | None- Identidad lógica opaca que asigna o recupera el runtime.
parent_execution_id: str | None- Identidad lógica de la ejecución padre, si existe.
InvocationTerminalEvent
Clase · Estable · agnara.execution
Evento de telemetría que identifica el final, duración y desenlace de una invocación.
InvocationTerminalEvent(
capability_id: CapabilityId,
tracking_id: str | None,
duration_ns: int,
outcome: str,
invocation_id: str,
units: int | None = None,
execution_id: str | None = None,
parent_execution_id: str | None = None,
) -> NoneParámetros
capability_id- Identificador lógico de la capacidad.
tracking_id- Etiqueta opcional de correlación externa. No concede autoridad.
duration_ns- Duración de la invocación en nanosegundos.
outcome- Desenlace de la invocación o resultado canónico que se proyecta.
invocation_id- Identificador del intento de invocación observado.
units- Cantidad de unidades del stream asociadas al evento terminal.
execution_id- Identidad lógica opaca que asigna o recupera el runtime.
parent_execution_id- Identidad lógica de la ejecución padre, si existe.
Atributos
capability_id: CapabilityId- Identificador lógico de la capacidad.
tracking_id: str | None- Etiqueta opcional de correlación externa. No concede autoridad.
duration_ns: int- Duración de la invocación en nanosegundos.
outcome: str- Desenlace de la invocación o resultado canónico que se proyecta.
invocation_id: str- Identificador del intento de invocación observado.
units: int | None- Cantidad de unidades del stream asociadas al evento terminal.
execution_id: str | None- Identidad lógica opaca que asigna o recupera el runtime.
parent_execution_id: str | None- Identidad lógica de la ejecución padre, si existe.
StreamInterrupted
Excepción · Estable · agnara.execution
Excepción de consumo que lleva el fallo canónico y el número de unidades ya entregadas.
StreamInterrupted(failure: Failure, units_emitted: int) -> None
Parámetros
failure- Fallo canónico que explica la interrupción o se proyecta al adaptador.
units_emitted- Cantidad de unidades entregadas antes de detenerse.
Atributos
failure: Failure- Fallo canónico que explica la interrupción o se proyecta al adaptador.
units_emitted: int- Cantidad de unidades entregadas antes de detenerse.
StreamTerminal
Enumeración · Estable · agnara.execution
Describe la forma en que acabó un stream.
COMPLETED = 'completed'- El productor terminó normalmente.
INTERRUPTED = 'interrupted'- La producción se interrumpió por un fallo.
CANCELLED = 'cancelled'- Se canceló el consumo o la ejecución.
TIMED_OUT = 'timed_out'- Se agotó el plazo del stream.
ABANDONED = 'abandoned'- El consumidor cerró el stream antes de agotarlo.
Success
Clase · Estable · agnara.execution
Resultado canónico satisfactorio con el valor producido y una identidad de ejecución opcional.
Success(value: T, execution_id: str | None = None) -> None
Parámetros
value- Valor satisfactorio producido por el handler.
execution_id- Identidad lógica opaca que asigna o recupera el runtime.
Atributos
value: T- Valor satisfactorio producido por el handler.
execution_id: str | None- Identidad lógica opaca que asigna o recupera el runtime.
TelemetryHook
Protocolo · Estable · agnara.execution
Protocolo síncrono para observar el inicio y el final de una invocación.
TelemetryHook.on_invocation_start Método
on_invocation_start(event: InvocationStartEvent) -> None
Recibe el evento previo a la adquisición de dependencias.
event- Evento de telemetría entregado al observador.
TelemetryHook.on_invocation_terminal Método
on_invocation_terminal(event: InvocationTerminalEvent) -> None
Recibe el evento de finalización con desenlace y duración.
event- Evento de telemetría entregado al observador.
classify_failure
Función · Estable · agnara.execution
Convierte una excepción en un fallo canónico y evita exponer diagnósticos internos de errores inesperados.
classify_failure(error: Exception, capability_id: CapabilityId) -> Failure
Parámetros
error- Excepción que se clasifica en el límite. La cancelación se propaga por separado.
capability_id- Identificador lógico de la capacidad.
invoke
Función asíncrona · Estable · agnara.execution
Ejecuta un plan con semántica ordinaria de Python. Devuelve el valor o propaga la excepción. Usa invoke_result() si el adaptador necesita un resultado canónico.
async invoke(plan: ExecutionPlan, context: ExecutionContext) -> Any
Parámetros
plan- Plan compilado que se va a ejecutar.
context- Contexto de la invocación que se va a evaluar o ejecutar.
invoke_result
Función asíncrona · Estable · agnara.execution
Ejecuta políticas, validación, dependencias y handler para una capacidad de resultado completo. Devuelve Success o Failure. La cancelación del llamador se propaga.
async invoke_result(
plan: ExecutionPlan,
context: ExecutionContext,
*,
input_materializer: Callable[[TypeSchema, object], object] | None = None,
) -> CanonicalResult[T]Parámetros
plan- Plan compilado que se va a ejecutar.
context- Contexto de la invocación que se va a evaluar o ejecutar.
input_materializer- Conversión de datos del límite de transporte a valores de entrada Python.
Un fallo inesperado se convierte en INTERNAL_FAILURE con mensaje redactado. Un plazo agotado se representa como TIMEOUT. La cancelación del llamador sigue siendo CancelledError.
open_stream
Función · Estable · agnara.execution
Prepara el contexto asíncrono de un stream. Entra con async with y consume con async for para liberar los recursos incluso al terminar temprano.
open_stream(
plan: ExecutionPlan,
context: ExecutionContext,
*,
input_materializer: Callable[[TypeSchema, object], object] | None = None,
) -> CapabilityStreamParámetros
plan- Plan compilado que se va a ejecutar.
context- Contexto de la invocación que se va a evaluar o ejecutar.
input_materializer- Conversión de datos del límite de transporte a valores de entrada Python.
El plazo alcanza la obtención de unidades. Los fallos posteriores al inicio pueden llegar como StreamInterrupted. El contexto asíncrono cierra el productor si se abandona la iteración.
5. Exposiciones compiladas
agnara.exposure · 7 exportaciones
Una exposición describe cómo se alcanza una capacidad en una superficie. El registro agregado permite consultar las superficies sin convertir el transporte en la definición de negocio.
Guía relacionada · API_DESIGN.md
CompiledExposure · ExposureError · ExposureId · FrozenExposureRegistry · SurfaceCompilation · SurfaceId · compile_exposures
CompiledExposure
Clase · Estable · agnara.exposure
Registro de una capacidad alcanzable a través de un destino de un adaptador, con detalles neutrales publicables.
CompiledExposure(
id: ExposureId,
capability_id: CapabilityId,
detail: str = '{}',
) -> NoneParámetros
id- Identificador del registro. Su tipo depende de la entidad.
capability_id- Identificador lógico de la capacidad.
detail- Detalle de exposición aportado por el adaptador como datos.
Atributos
id: ExposureId- Identificador del registro. Su tipo depende de la entidad.
capability_id: CapabilityId- Identificador lógico de la capacidad.
detail: str- Detalle de exposición aportado por el adaptador como datos.
CompiledExposure.of Método
of(
surface: SurfaceId,
name: str,
capability_id: CapabilityId,
detail: object = None,
) -> CompiledExposureConstruye una exposición y normaliza los detalles aportados por el adaptador.
surface- Identidad o nombre de la superficie que sirve la exposición.
name- Nombre lógico de la entidad que se declara, describe o publica.
capability_id- Identificador lógico de la capacidad.
detail- Detalle de exposición aportado por el adaptador como datos.
CompiledExposure.surface Propiedad
Identidad de la superficie del adaptador que ofrece el destino. SurfaceId
CompiledExposure.published_detail Método
published_detail() -> dict[str, Any]
Devuelve los detalles publicables como datos JSON e incluye el nombre de la superficie.
ExposureError
Excepción · Estable · agnara.exposure
La declaración o combinación de exposiciones no satisface el contrato.
ExposureId
Clase · Estable · agnara.exposure
Identifica un destino dentro de una superficie de un adaptador.
ExposureId(surface: SurfaceId, name: str) -> None
Parámetros
surface- Identidad o nombre de la superficie que sirve la exposición.
name- Nombre lógico de la entidad que se declara, describe o publica.
Atributos
surface: SurfaceId- Identidad o nombre de la superficie que sirve la exposición.
name: str- Nombre lógico de la entidad que se declara, describe o publica.
ExposureId.adapter Propiedad
Protocolo al que pertenece este destino. str
FrozenExposureRegistry
Clase · Estable · agnara.exposure
Vista inmutable y ordenada de las exposiciones compiladas de un proyecto.
FrozenExposureRegistry(exposures: Iterable[CompiledExposure] = ()) -> None
Parámetros
exposures- Colección de destinos compilados de la superficie o del proyecto.
FrozenExposureRegistry.__getitem__ Método
__getitem__(key: ExposureId) -> CompiledExposure
Busca un elemento por su clave.
key- Selector de idempotencia aportado por el cliente o la aplicación y acotado por identidad y capacidad.
FrozenExposureRegistry.__iter__ Método
__iter__() -> Iterator[ExposureId]
Recorre las claves de la colección.
FrozenExposureRegistry.__len__ Método
__len__() -> int
Devuelve la cantidad de declaraciones o elementos de la colección.
FrozenExposureRegistry.surfaces Propiedad
Superficies que aportaron exposiciones, en el orden de agregación. tuple[SurfaceId, ...]
FrozenExposureRegistry.for_capability Método
for_capability(capability_id: CapabilityId) -> tuple[CompiledExposure, ...]
Filtra los destinos compilados de la capacidad.
capability_id- Identificador lógico de la capacidad.
FrozenExposureRegistry.on_surface Método
on_surface(surface: SurfaceId) -> tuple[CompiledExposure, ...]
Filtra los destinos de la superficie en su orden de emisión.
surface- Identidad o nombre de la superficie que sirve la exposición.
FrozenExposureRegistry.transports Método
transports(capability_id: CapabilityId) -> tuple[str, ...]
Devuelve los protocolos de exposición sin repeticiones y en orden de aparición.
capability_id- Identificador lógico de la capacidad.
SurfaceCompilation
Clase · Estable · agnara.exposure
Agrupa el artefacto operativo de una superficie y los registros neutrales que aporta.
SurfaceCompilation(
surface: SurfaceId,
runtime: RuntimeT,
exposures: tuple[CompiledExposure, ...] = (),
) -> NoneParámetros
surface- Identidad o nombre de la superficie que sirve la exposición.
runtime- Artefacto de ejecución de la superficie o runtime compilado que despacha la invocación.
exposures- Colección de destinos compilados de la superficie o del proyecto.
Atributos
surface: SurfaceId- Identidad o nombre de la superficie que sirve la exposición.
runtime: RuntimeT- Artefacto de ejecución de la superficie o runtime compilado que despacha la invocación.
exposures: tuple[CompiledExposure, ...]- Colección de destinos compilados de la superficie o del proyecto.
SurfaceId
Clase · Estable · agnara.exposure
Identifica una superficie por adaptador y nombre.
SurfaceId(adapter: str, name: str) -> None
Parámetros
adapter- Identificador del adaptador o protocolo al que pertenece la superficie.
name- Nombre lógico de la entidad que se declara, describe o publica.
Atributos
adapter: str- Identificador del adaptador o protocolo al que pertenece la superficie.
name: str- Nombre lógico de la entidad que se declara, describe o publica.
compile_exposures
Función · Estable · agnara.exposure
Reúne las superficies compiladas y comprueba que sus destinos pertenezcan al conjunto de capacidades del proyecto.
compile_exposures(
capabilities: FrozenCapabilityRegistry,
compilations: Iterable[SurfaceCompilation[Any]] = (),
) -> FrozenExposureRegistryParámetros
capabilities- Conjunto de capacidades declaradas o compiladas que delimita la composición.
compilations- Artefactos de las superficies ya compiladas.
6. Introspección y publicación
agnara.introspection · 23 exportaciones
Describe aplicaciones compiladas, aplica visibilidad para el lector y serializa el resultado filtrado. El permiso para descubrir una capacidad es independiente de su permiso de ejecución.
Guía relacionada · INTROSPECTION.md
INTROSPECTION_FORMAT · INTROSPECTION_VERSION · AllCapabilitiesVisible · ApplicationDescriptor · BoundedContextDescriptor · CapabilityDescriptor · DependencyDescriptor · DiscoveryField · DiscoveryVisibility · ExposureDescriptor · Hiding · InputDescriptor · IntrospectionError · IntrospectionSnapshot · NoCapabilityVisible · PolicyDescriptor · ProviderDescriptor · ScopeVisible · TypeReference · VisibilityRule · describe_app · filter_snapshot · snapshot
Constante · Estable · agnara.introspection
Identificador del formato de instantáneas de introspección.
INTROSPECTION_FORMAT = 'agnara-introspection'
INTROSPECTION_VERSION
Constante · Estable · agnara.introspection
Versión del formato de introspección, independiente de la versión del paquete.
INTROSPECTION_VERSION = '1'
AllCapabilitiesVisible
Clase · Estable · agnara.introspection
Regla que hace visible toda capacidad a cualquier lector. Útil para desarrollo y herramientas locales.
AllCapabilitiesVisible() -> None
AllCapabilitiesVisible.visible Método
visible(capability: CapabilityDescriptor, principal: Principal, /) -> bool
Autoriza el descubrimiento para cualquier lector.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
principal- Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.
ApplicationDescriptor
Clase · Estable · agnara.introspection
Descripción de una aplicación compilada con capacidades, proveedores y contextos montados.
ApplicationDescriptor(
name: str,
capabilities: tuple[CapabilityDescriptor, ...] = (),
providers: tuple[ProviderDescriptor, ...] = (),
apps: tuple[BoundedContextDescriptor, ...] = (),
) -> NoneParámetros
name- Nombre lógico de la entidad que se declara, describe o publica.
capabilities- Conjunto de capacidades declaradas o compiladas que delimita la composición.
providers- Descriptores del grafo de proveedores.
apps- Contextos delimitados montados.
Atributos
name: str- Nombre lógico de la entidad que se declara, describe o publica.
capabilities: tuple[CapabilityDescriptor, ...]- Conjunto de capacidades declaradas o compiladas que delimita la composición.
providers: tuple[ProviderDescriptor, ...]- Descriptores del grafo de proveedores.
apps: tuple[BoundedContextDescriptor, ...]- Contextos delimitados montados.
ApplicationDescriptor.transports Propiedad
Devuelve los protocolos de exposición sin repeticiones y en orden de aparición. tuple[str, ...]
ApplicationDescriptor.json_data Método
json_data() -> dict[str, Any]
Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.
BoundedContextDescriptor
Clase · Estable · agnara.introspection
Descripción de un contexto delimitado montado en una aplicación.
BoundedContextDescriptor(name: str, description: str | None = None) -> None
Parámetros
name- Nombre lógico de la entidad que se declara, describe o publica.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
Atributos
name: str- Nombre lógico de la entidad que se declara, describe o publica.
description: str | None- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
BoundedContextDescriptor.json_data Método
json_data() -> dict[str, Any]
Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.
CapabilityDescriptor
Clase · Estable · agnara.introspection
Metadatos de una capacidad compilada para descubrimiento. El descriptor no transporta la función ejecutable.
CapabilityDescriptor(
id: str,
description: str | None = None,
effects: tuple[str, ...] = (),
scopes: tuple[str, ...] = (),
risk: str = 'low',
confirmation: str = 'never',
idempotency: str = 'unknown',
inputs: tuple[InputDescriptor, ...] = (),
dependencies: tuple[DependencyDescriptor, ...] = (),
policies: tuple[PolicyDescriptor, ...] = (),
exposures: tuple[ExposureDescriptor, ...] = (),
) -> NoneParámetros
id- Identificador del registro. Su tipo depende de la entidad.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
effects- Conjunto de etiquetas que describe los efectos de la capacidad.
scopes- Permisos declarados por la capacidad o concedidos a una identidad verificada.
risk- Clasificación del impacto potencial de una invocación incorrecta.
confirmation- Régimen de confirmación declarado para la capacidad.
idempotency- Metadato de repetición segura o configuración explícita de reserva, según el tipo indicado.
inputs- Descriptores de entrada publicables.
dependencies- Registro de dependencias para composición o descriptores de dependencias en introspección.
policies- Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
exposures- Colección de destinos compilados de la superficie o del proyecto.
Atributos
id: str- Identificador del registro. Su tipo depende de la entidad.
description: str | None- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
effects: tuple[str, ...]- Conjunto de etiquetas que describe los efectos de la capacidad.
scopes: tuple[str, ...]- Permisos declarados por la capacidad o concedidos a una identidad verificada.
risk: str- Clasificación del impacto potencial de una invocación incorrecta.
confirmation: str- Régimen de confirmación declarado para la capacidad.
idempotency: str- Metadato de repetición segura o configuración explícita de reserva, según el tipo indicado.
inputs: tuple[InputDescriptor, ...]- Descriptores de entrada publicables.
dependencies: tuple[DependencyDescriptor, ...]- Registro de dependencias para composición o descriptores de dependencias en introspección.
policies: tuple[PolicyDescriptor, ...]- Reglas evaluadas antes de adquirir dependencias y ejecutar el handler.
exposures: tuple[ExposureDescriptor, ...]- Colección de destinos compilados de la superficie o del proyecto.
CapabilityDescriptor.transports Propiedad
Devuelve los protocolos de exposición sin repeticiones y en orden de aparición. tuple[str, ...]
CapabilityDescriptor.json_data Método
json_data() -> dict[str, Any]
Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.
DependencyDescriptor
Clase · Estable · agnara.introspection
Describe por nombre y tipo una dependencia declarada por una capacidad.
DependencyDescriptor(parameter: str, type: TypeReference) -> None
Parámetros
parameter- Nombre del parámetro de la función que solicita la dependencia.
type- Referencia descriptiva del tipo solicitado.
Atributos
parameter: str- Nombre del parámetro de la función que solicita la dependencia.
type: TypeReference- Referencia descriptiva del tipo solicitado.
DependencyDescriptor.json_data Método
json_data() -> dict[str, Any]
Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.
DiscoveryField
Enumeración · Estable · agnara.introspection
Enumera los campos de descubrimiento que pueden habilitarse de forma independiente.
DESCRIPTION = 'description'- Descripción textual.
EFFECTS = 'effects'- Etiquetas de efectos.
SCOPES = 'scopes'- Permisos declarados.
SAFETY = 'safety'- Metadatos de riesgo, confirmación e idempotencia.
INPUTS = 'inputs'- Parámetros de entrada y sus esquemas.
DEPENDENCIES = 'dependencies'- Dependencias declaradas por capacidades.
PROVIDERS = 'providers'- Descriptores de proveedores.
APPS = 'apps'- Contextos delimitados montados.
POLICIES = 'policies'- Tipos de políticas adjuntas.
EXPOSURES = 'exposures'- Destinos de los adaptadores.
EXPOSURE_DETAIL = 'exposure_detail'- Detalles adicionales de los destinos.
TYPE_MODULES = 'type_modules'- Nombres de módulo de los tipos.
DiscoveryVisibility
Clase · Estable · agnara.introspection
Combina una regla de acceso con el conjunto de campos a publicar.
DiscoveryVisibility(
rule: VisibilityRule,
published: Iterable[DiscoveryField | str],
) -> NoneParámetros
rule- Regla que decide qué capacidades son visibles para el lector.
published- Campos que la decisión de descubrimiento permite publicar.
Atributos
rule: VisibilityRule- Regla que decide qué capacidades son visibles para el lector.
published: frozenset[DiscoveryField]- Campos que la decisión de descubrimiento permite publicar.
DiscoveryVisibility.publishes Método
publishes(field: DiscoveryField) -> bool
Comprueba si la configuración habilita la publicación de ese campo.
field- Campo de descubrimiento que se consulta.
DiscoveryVisibility.identity_only Método
identity_only(rule: VisibilityRule) -> DiscoveryVisibility
Publica la identidad de las capacidades que admite la regla.
rule- Regla que decide la visibilidad de una capacidad.
DiscoveryVisibility.agent_safe Método
agent_safe(rule: VisibilityRule) -> DiscoveryVisibility
Habilita campos para que un agente pueda elegir y utilizar las capacidades visibles.
rule- Regla que decide la visibilidad de una capacidad.
DiscoveryVisibility.unrestricted Método
unrestricted(rule: VisibilityRule) -> DiscoveryVisibility
Habilita todos los campos. Adecuado para herramientas locales y desarrollo controlado.
rule- Regla que decide la visibilidad de una capacidad.
ExposureDescriptor
Clase · Estable · agnara.introspection
Vista serializable de un destino publicado por un adaptador.
ExposureDescriptor(transport: str, name: str, detail: str = '{}') -> NoneParámetros
transport- Nombre del protocolo de una exposición.
name- Nombre lógico de la entidad que se declara, describe o publica.
detail- Detalle de exposición aportado por el adaptador como datos.
Atributos
transport: str- Nombre del protocolo de una exposición.
name: str- Nombre lógico de la entidad que se declara, describe o publica.
detail: str- Detalle de exposición aportado por el adaptador como datos.
ExposureDescriptor.of Método
of(transport: str, name: str, detail: object = None) -> ExposureDescriptor
Construye un descriptor neutral desde protocolo, nombre y detalle publicable.
transport- Nombre del protocolo de una exposición.
name- Nombre lógico de la entidad que se declara, describe o publica.
detail- Detalle de exposición aportado por el adaptador como datos.
ExposureDescriptor.json_data Método
json_data() -> dict[str, Any]
Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.
Hiding
Clase · Estable · agnara.introspection
Oculta identificadores concretos y delega el resto de la decisión a otra regla.
Hiding(ids: Iterable[str], rule: VisibilityRule) -> None
Parámetros
ids- Identificadores que la regla oculta.
rule- Regla que decide la visibilidad de una capacidad.
Atributos
ids: frozenset[str]- Identificadores que la regla oculta.
rule: VisibilityRule- Regla que decide la visibilidad de una capacidad.
Hiding.visible Método
visible(capability: CapabilityDescriptor, principal: Principal, /) -> bool
Rechaza identificadores ocultos y aplica la regla de respaldo a los demás.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
principal- Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.
Clase · Estable · agnara.introspection
Describe un argumento de entrada, su obligatoriedad y su esquema publicado.
InputDescriptor(name: str, required: bool, schema: str) -> None
Parámetros
name- Nombre lógico de la entidad que se declara, describe o publica.
required- Indica si la entrada es obligatoria.
schema- Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.
Atributos
name: str- Nombre lógico de la entidad que se declara, describe o publica.
required: bool- Indica si la entrada es obligatoria.
schema: str- Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.
of(name: str, *, required: bool, schema: object) -> InputDescriptor
Construye un descriptor de entrada con su obligatoriedad y esquema.
name- Nombre lógico de la entidad que se declara, describe o publica.
required- Indica si la entrada es obligatoria.
schema- Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.
json_data() -> dict[str, Any]
Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.
IntrospectionError
Excepción · Estable · agnara.introspection
No se pudo construir una instantánea a partir de la superficie compilada proporcionada.
IntrospectionSnapshot
Clase · Estable · agnara.introspection
Vista inmutable y versionada de las aplicaciones compiladas de un proyecto.
IntrospectionSnapshot(
applications: tuple[ApplicationDescriptor, ...] = (),
project: str | None = None,
format: str = 'agnara-introspection',
version: str = '1',
filtered: bool = False,
) -> NoneParámetros
applications- Descriptores de las aplicaciones incluidas.
project- Identificador del proyecto de introspección.
format- Identificador del formato serializado.
version- Versión anunciada por el documento, agente, servidor o formato.
filtered- Indica si la instantánea ya se filtró para su publicación.
Atributos
applications: tuple[ApplicationDescriptor, ...]- Descriptores de las aplicaciones incluidas.
project: str | None- Identificador del proyecto de introspección.
format: str- Identificador del formato serializado.
version: str- Versión anunciada por el documento, agente, servidor o formato.
filtered: bool- Indica si la instantánea ya se filtró para su publicación.
IntrospectionSnapshot.transports Propiedad
Devuelve los protocolos de exposición sin repeticiones y en orden de aparición. tuple[str, ...]
IntrospectionSnapshot.json_data Método
json_data() -> dict[str, Any]
Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.
NoCapabilityVisible
Clase · Estable · agnara.introspection
Regla que oculta todas las capacidades.
NoCapabilityVisible() -> None
NoCapabilityVisible.visible Método
visible(capability: CapabilityDescriptor, principal: Principal, /) -> bool
Deniega el descubrimiento para cualquier lector.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
principal- Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.
PolicyDescriptor
Clase · Estable · agnara.introspection
Identifica el tipo de una política sin exponer su configuración ejecutable.
PolicyDescriptor(kind: str) -> None
Parámetros
kind- Categoría de interacción, proveedor o descriptor según el tipo indicado.
Atributos
kind: str- Categoría de interacción, proveedor o descriptor según el tipo indicado.
PolicyDescriptor.json_data Método
json_data() -> dict[str, Any]
Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.
ProviderDescriptor
Clase · Estable · agnara.introspection
Describe un proveedor como nodo del grafo de dependencias sin incluir su función.
ProviderDescriptor(
provides: TypeReference,
scope: str,
kind: str,
requires: tuple[TypeReference, ...] = (),
) -> NoneParámetros
provides- Tipo que suministra la asociación.
scope- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
kind- Categoría de interacción, proveedor o descriptor según el tipo indicado.
requires- Tipos que el proveedor necesita para construirse.
Atributos
provides: TypeReference- Tipo que suministra la asociación.
scope: str- Duración del proveedor, selector de idempotencia o ámbito ASGI, según el tipo indicado.
kind: str- Categoría de interacción, proveedor o descriptor según el tipo indicado.
requires: tuple[TypeReference, ...]- Tipos que el proveedor necesita para construirse.
ProviderDescriptor.json_data Método
json_data() -> dict[str, Any]
Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.
ScopeVisible
Clase · Estable · agnara.introspection
Solo permite descubrir capacidades cuyos permisos declarados están presentes en la identidad del lector.
ScopeVisible() -> None
ScopeVisible.visible Método
visible(capability: CapabilityDescriptor, principal: Principal, /) -> bool
Autoriza el descubrimiento cuando el lector posee los permisos declarados.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
principal- Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.
TypeReference
Clase · Estable · agnara.introspection
Representación descriptiva del nombre de un tipo sin conservar el objeto Python.
TypeReference(name: str, module: str | None = None) -> None
Parámetros
name- Nombre lógico de la entidad que se declara, describe o publica.
module- Nombre de módulo de procedencia que puede aparecer en el descriptor.
Atributos
name: str- Nombre lógico de la entidad que se declara, describe o publica.
module: str | None- Nombre de módulo de procedencia que puede aparecer en el descriptor.
TypeReference.of Método
of(annotation: type) -> TypeReference
Describe la anotación por nombre sin conservar el objeto Python.
annotation- Anotación de tipo Python que se describe o compila.
TypeReference.json_data Método
json_data() -> dict[str, Any]
Convierte el descriptor o la instantánea en datos serializables. Aplica el filtro de descubrimiento antes de compartir una instantánea.
VisibilityRule
Protocolo · Estable · agnara.introspection
Protocolo para decidir si un lector puede descubrir una capacidad.
VisibilityRule.visible Método
visible(capability: CapabilityDescriptor, principal: Principal, /) -> bool
Decide si la identidad indicada puede descubrir la capacidad.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
principal- Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.
describe_app
Función · Estable · agnara.introspection
Construye descriptores de una aplicación a partir de sus planes y datos de composición.
describe_app(
app: Agnara,
plans: Iterable[ExecutionPlan],
*,
exposures: ExposureSource | None = None,
dependencies: DIRegistry | None = None,
) -> ApplicationDescriptorParámetros
app- Aplicación o contexto que posee las declaraciones.
plans- Planes compilados que la superficie puede despachar o describir.
exposures- Colección de destinos compilados de la superficie o del proyecto.
dependencies- Registro de dependencias para composición o descriptores de dependencias en introspección.
filter_snapshot
Función · Estable · agnara.introspection
Aplica visibilidad y selección de campos antes de serializar una instantánea para un lector.
filter_snapshot(
snapshot: IntrospectionSnapshot,
visibility: DiscoveryVisibility,
principal: Principal,
) -> IntrospectionSnapshotParámetros
snapshot- Instantánea de introspección que se filtra o publica.
visibility- Regla de visibilidad y selección de campos para la instantánea.
principal- Identidad de confianza asociada al actor o lector. None permite el tratamiento anónimo según el contrato.
Aplica este filtro antes de usar json_data() para un lector externo. La publicación de un identificador o una etiqueta no concede autoridad.
snapshot
Función · Estable · agnara.introspection
Combina descriptores de aplicaciones en una instantánea versionada.
snapshot(
applications: Iterable[ApplicationDescriptor],
*,
project: str | None = None,
) -> IntrospectionSnapshotParámetros
applications- Descriptores de las aplicaciones incluidas.
project- Identificador del proyecto de introspección.
7. Confirmación de invocaciones
agnara.policy · 1 exportaciones
La evidencia llega desde el host y un verificador la vincula a la invocación. El llamador puede recibir una solicitud de interacción cuando falta una confirmación válida.
Guía relacionada · CONFIRMATION.md
ConfirmationPolicy
ConfirmationPolicy
Clase · Estable · agnara.policy
Política que exige evidencia verificada para continuar. Puede devolver una solicitud de interacción.
ConfirmationPolicy(capability_id: CapabilityId, verifier: ConfirmationVerifier) -> None
Parámetros
capability_id- Identificador lógico de la capacidad.
verifier- Autoridad de la aplicación que comprueba evidencia de confirmación.
Atributos
capability_id: CapabilityId- Identificador lógico de la capacidad.
verifier: ConfirmationVerifier- Autoridad de la aplicación que comprueba evidencia de confirmación.
request: InteractionRequest- Solicitud de interacción que explica al llamador cómo continuar.
ConfirmationPolicy.evaluate Método
async evaluate(context: ExecutionContext) -> PolicyResult
Consulta la evidencia y su verificador. Si se requiere interacción, detiene la invocación y devuelve la solicitud correspondiente.
context- Contexto de la invocación que se va a evaluar o ejecutar.
8. Esquemas y datos JSON
agnara.schema · 13 exportaciones
La validación directa comprueba tipos Python. En el límite de un transporte, la materialización explícita puede convertir estructuras JSON a dataclasses, tuplas o miembros de enum. La proyección JSON realiza la operación de salida.
Guía relacionada · SCHEMA_CONTRACTS.md
AnySchema · DataclassFieldSchema · DataclassSchema · DictionarySchema · EnumSchema · ListSchema · LiteralSchema · NoneSchema · PrimitiveSchema · TupleSchema · UnionSchema · materialize_json · serialize_json
AnySchema
Clase · Estable · agnara.schema
Esquema que admite cualquier valor Python.
AnySchema() -> None
AnySchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
AnySchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
DataclassFieldSchema
Clase · Estable · agnara.schema
Describe un campo de dataclass con su esquema recursivo y su obligatoriedad.
DataclassFieldSchema(name: str, schema: TypeSchema, required: bool) -> None
Parámetros
name- Nombre lógico de la entidad que se declara, describe o publica.
schema- Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.
required- Indica si la entrada es obligatoria.
Atributos
name: str- Nombre lógico de la entidad que se declara, describe o publica.
schema: TypeSchema- Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.
required: bool- Indica si la entrada es obligatoria.
DataclassSchema
Clase · Estable · agnara.schema
Comprueba instancias de una dataclass y los valores de sus campos.
DataclassSchema(dataclass_type: type, fields: tuple[DataclassFieldSchema, ...]) -> None
Parámetros
dataclass_type- Clase dataclass concreta que admite el esquema.
fields- Campos compilados de la dataclass.
Atributos
dataclass_type: type- Clase dataclass concreta que admite el esquema.
fields: tuple[DataclassFieldSchema, ...]- Campos compilados de la dataclass.
DataclassSchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
DataclassSchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
DictionarySchema
Clase · Estable · agnara.schema
Comprueba un diccionario de claves de texto con un esquema homogéneo para los valores.
DictionarySchema(value_schema: TypeSchema) -> None
Parámetros
value_schema- Esquema común de los valores del diccionario.
Atributos
value_schema: TypeSchema- Esquema común de los valores del diccionario.
DictionarySchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
DictionarySchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
EnumSchema
Clase · Estable · agnara.schema
Comprueba miembros de una enumeración específica y proyecta los valores representables en JSON.
EnumSchema(enum_type: type[Enum], values: tuple[object, ...]) -> None
Parámetros
enum_type- Clase de enumeración admitida por el esquema.
values- Valores admitidos por la enumeración o literal.
Atributos
enum_type: type[Enum]- Clase de enumeración admitida por el esquema.
values: tuple[object, ...]- Valores admitidos por la enumeración o literal.
EnumSchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
EnumSchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
ListSchema
Clase · Estable · agnara.schema
Comprueba una lista y valida cada elemento con el mismo esquema.
ListSchema(item_schema: TypeSchema) -> None
Parámetros
item_schema- Esquema que se aplica a cada elemento.
Atributos
item_schema: TypeSchema- Esquema que se aplica a cada elemento.
ListSchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
ListSchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
LiteralSchema
Clase · Estable · agnara.schema
Admite una selección finita de escalares exactos compatibles con JSON.
LiteralSchema(values: tuple[object, ...]) -> None
Parámetros
values- Valores admitidos por la enumeración o literal.
Atributos
values: tuple[object, ...]- Valores admitidos por la enumeración o literal.
LiteralSchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
LiteralSchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
NoneSchema
Clase · Estable · agnara.schema
Admite únicamente None.
NoneSchema() -> None
NoneSchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
NoneSchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
PrimitiveSchema
Clase · Estable · agnara.schema
Comprueba que el valor tenga exactamente el tipo primitivo indicado.
PrimitiveSchema(python_type: type) -> None
Parámetros
python_type- Tipo primitivo exacto que exige el esquema.
Los tipos se comprueban de forma exacta. Por ejemplo, True no satisface un contrato int.
Atributos
python_type: type- Tipo primitivo exacto que exige el esquema.
PrimitiveSchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
PrimitiveSchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
TupleSchema
Clase · Estable · agnara.schema
Comprueba una tupla fija por posición o una tupla variádica con elementos homogéneos.
TupleSchema(item_schemas: tuple[TypeSchema, ...], variadic: bool = False) -> None
Parámetros
item_schemas- Esquemas por posición o esquema repetido de la tupla.
variadic- Distingue una tupla homogénea de longitud variable de una tupla posicional.
Atributos
item_schemas: tuple[TypeSchema, ...]- Esquemas por posición o esquema repetido de la tupla.
variadic: bool- Distingue una tupla homogénea de longitud variable de una tupla posicional.
TupleSchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
TupleSchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
UnionSchema
Clase · Estable · agnara.schema
Admite un valor aceptado por al menos uno de los esquemas de la unión.
UnionSchema(choices: tuple[TypeSchema, ...]) -> None
Parámetros
choices- Esquemas alternativos que acepta la unión.
Atributos
choices: tuple[TypeSchema, ...]- Esquemas alternativos que acepta la unión.
UnionSchema.validate Método
validate(value: object) -> Any
Comprueba el valor Python de acuerdo con este esquema. Cuando el contrato no se satisface, informa un ValidationError.
value- Valor que se valida, contiene o transforma.
UnionSchema.json_schema Método
json_schema() -> JsonSchema
Proyecta el esquema compilado a datos JSON Schema.
materialize_json
Función · Estable · agnara.schema
Convierte datos JSON ya decodificados en valores Python para un esquema compatible. Por ejemplo, puede construir la dataclass que espera un handler.
materialize_json(schema: TypeSchema, value: object) -> Any
Parámetros
schema- Esquema compilado, definición JSON Schema o publicación OpenAPI según el tipo indicado.
value- Valor que se valida, contiene o transforma.
Espera un valor JSON ya decodificado. Puede materializar una dataclass, tupla o enum antes de validar. Un esquema no reconocido recibe el valor sin conversión.
serialize_json
Función · Estable · agnara.schema
Proyecta un valor de Python a datos JSON. Devuelve los datos estructurados para el codificador, no una cadena JSON.
serialize_json(value: object) -> Any
Parámetros
value- Valor que se valida, contiene o transforma.
Emite objetos y arrays JSON como estructuras Python. Lanza ValidationError para valores incompatibles, números no finitos, claves de objeto ajenas a str o ciclos. La profundidad está acotada.
9. Adaptador HTTP
agnara_http · 14 exportaciones
Registra rutas con bindings explícitos y compílalas antes de servir. El servidor ASGI gestiona lifespan. OpenAPI, sus interfaces web y Explorer se habilitan de forma explícita con sus propios controles de publicación.
Guía relacionada · HTTP_COMPOSITION.md
Binding · BindingSource · DocumentationAssets · Http · HttpApplication · HttpDefinitionError · HttpDocumentation · HttpExplorer · OpenApiInfo · OpenApiOperation · OpenApiSchema · ReDoc · Scalar · SwaggerUI
Binding
Clase · Estable · agnara_http
Indica de qué parte de una petición HTTP procede un argumento de la capacidad.
Binding(input_name: str, source: BindingSource, *, wire_name: str | None = None) -> None
Parámetros
input_name- Parámetro de capacidad que se llena desde la petición.
source- Ubicación de la petición desde la que se lee el argumento.
wire_name- Nombre en la petición cuando difiere del parámetro de capacidad.
Parámetro de capacidad que se llena desde la petición. str
Binding.source Propiedad
Ubicación de la petición desde la que se lee el argumento. BindingSource
Binding.wire_name Propiedad
Nombre en la petición cuando difiere del parámetro de capacidad. str | None
BindingSource
Enumeración · Estable · agnara_http
Enumera las fuentes HTTP admitidas para rellenar argumentos de una capacidad.
PATH = 'path'- Parámetro extraído de la ruta.
QUERY = 'query'- Parámetro extraído de la cadena de consulta.
HEADER = 'header'- Valor extraído de una cabecera.
BODY = 'body'- Valor leído del cuerpo JSON.
COOKIE = 'cookie'- Valor leído de una cookie.
FORM = 'form'- Campo de un formulario.
UPLOAD = 'upload'- Archivo recibido mediante un formulario multipart.
DocumentationAssets
Clase · Estable · agnara_http
Elige recursos locales verificados o habilita explícitamente orígenes HTTPS para recursos CDN fijados.
DocumentationAssets(
allowed_remote_origins: frozenset[str] = frozenset(),
remote_assets: bool = False,
) -> NoneParámetros
allowed_remote_origins- Orígenes HTTPS exactos que pueden proporcionar los recursos remotos fijados.
remote_assets- Selección explícita de recursos remotos.
Atributos
allowed_remote_origins: frozenset[str]- Orígenes HTTPS exactos que pueden proporcionar los recursos remotos fijados.
remote_assets: bool- Selección explícita de recursos remotos.
DocumentationAssets.local Método
local() -> Self
Selecciona recursos locales verificados por hash.
DocumentationAssets.remote Método
remote(*origins: str) -> Self
Habilita recursos CDN fijados cuando coinciden con un origen HTTPS explícito.
origins- Orígenes HTTPS explícitos habilitados para recursos remotos.
Http
Clase · Estable · agnara_http
Declara rutas de una superficie HTTP y las compila en una aplicación ASGI inmutable. Los bindings son explícitos.
Http(surface: str = 'default') -> None
Parámetros
surface- Identidad o nombre de la superficie que sirve la exposición.
Declara la relación entre método, ruta y capacidad en el adaptador. Las rutas publicadas en OpenAPI se seleccionan explícitamente.
Http.surface Propiedad
Identidad de esta superficie HTTP para el registro de exposiciones. SurfaceId
Http.is_compiled Propiedad
Indica que se cerró la declaración de rutas. bool
Http.route Método
route(
method: str,
path: str,
capability: CapabilityRef,
*bindings: Binding,
openapi: OpenApiOperation | None = None,
max_body_bytes: int | None = None,
max_parts: int | None = None,
) -> SelfRegistra la ruta con método y bindings explícitos para la capacidad indicada.
method- Método HTTP de la ruta.
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
bindings- Asignaciones de partes de la petición a entradas de la capacidad.
openapi- Opciones de publicación de OpenAPI para esta declaración o compilación.
max_body_bytes- Tamaño máximo del cuerpo admitido en bytes.
max_parts- Número máximo de partes permitido para multipart.
Http.get Método
get(
path: str,
capability: CapabilityRef,
*bindings: Binding,
openapi: OpenApiOperation | None = None,
) -> SelfRegistra una ruta GET. El compilador también proporciona HEAD.
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
bindings- Asignaciones de partes de la petición a entradas de la capacidad.
openapi- Opciones de publicación de OpenAPI para esta declaración o compilación.
Http.post Método
post(
path: str,
capability: CapabilityRef,
*bindings: Binding,
openapi: OpenApiOperation | None = None,
max_body_bytes: int | None = None,
max_parts: int | None = None,
) -> SelfRegistra una ruta POST y permite limitar el cuerpo y sus partes.
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
bindings- Asignaciones de partes de la petición a entradas de la capacidad.
openapi- Opciones de publicación de OpenAPI para esta declaración o compilación.
max_body_bytes- Tamaño máximo del cuerpo admitido en bytes.
max_parts- Número máximo de partes permitido para multipart.
Http.put Método
put(
path: str,
capability: CapabilityRef,
*bindings: Binding,
openapi: OpenApiOperation | None = None,
max_body_bytes: int | None = None,
max_parts: int | None = None,
) -> SelfRegistra una ruta PUT y permite limitar el cuerpo y sus partes.
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
bindings- Asignaciones de partes de la petición a entradas de la capacidad.
openapi- Opciones de publicación de OpenAPI para esta declaración o compilación.
max_body_bytes- Tamaño máximo del cuerpo admitido en bytes.
max_parts- Número máximo de partes permitido para multipart.
Http.patch Método
patch(
path: str,
capability: CapabilityRef,
*bindings: Binding,
openapi: OpenApiOperation | None = None,
max_body_bytes: int | None = None,
max_parts: int | None = None,
) -> SelfRegistra una ruta PATCH y permite limitar el cuerpo y sus partes.
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
bindings- Asignaciones de partes de la petición a entradas de la capacidad.
openapi- Opciones de publicación de OpenAPI para esta declaración o compilación.
max_body_bytes- Tamaño máximo del cuerpo admitido en bytes.
max_parts- Número máximo de partes permitido para multipart.
Http.delete Método
delete(
path: str,
capability: CapabilityRef,
*bindings: Binding,
openapi: OpenApiOperation | None = None,
) -> SelfRegistra una ruta DELETE.
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
bindings- Asignaciones de partes de la petición a entradas de la capacidad.
openapi- Opciones de publicación de OpenAPI para esta declaración o compilación.
Http.sse Método
sse(
path: str,
capability: CapabilityRef,
*bindings: Binding,
max_event_bytes: int | None = None,
) -> SelfExpone una capacidad de streaming en GET como eventos SSE.
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
bindings- Asignaciones de partes de la petición a entradas de la capacidad.
max_event_bytes- Tamaño máximo de un evento SSE en bytes.
Http.compile Método
compile(
capabilities: FrozenCapabilityRegistry,
*,
dependencies: DIRegistry | None = None,
openapi: OpenApiInfo | None = None,
openapi_path: str | None = None,
documentation: HttpDocumentation | None = None,
explorer: HttpExplorer | None = None,
lifecycle: Lifecycle | None = None,
request_timeout: float | None = None,
problem_base_uri: str | None = None,
hooks: Sequence[TelemetryHook] = (),
confirmation_verifier: ConfirmationVerifier | None = None,
schema_adapter: SchemaAdapter | None = None,
) -> HttpApplicationValida rutas y dependencias y construye una aplicación ASGI inmutable.
capabilities- Conjunto de capacidades declaradas o compiladas que delimita la composición.
dependencies- Registro de dependencias para composición o descriptores de dependencias en introspección.
openapi- Opciones de publicación de OpenAPI para esta declaración o compilación.
openapi_path- Ruta que publica el documento OpenAPI generado.
documentation- Configuración explícita de OpenAPI y sus interfaces.
explorer- Configuración de la interfaz Explorer.
lifecycle- Contexto de ciclo de vida ASGI que aporta el host.
request_timeout- Presupuesto de tiempo de una petición HTTP en segundos.
problem_base_uri- URI base para los tipos de problemas HTTP.
hooks- Observadores de telemetría del plan o de la superficie.
confirmation_verifier- Verificador que la aplicación suministra al compilar.
schema_adapter- Adaptador que compila anotaciones en esquemas.
Http.__len__ Método
__len__() -> int
Devuelve la cantidad de declaraciones o elementos de la colección.
HttpApplication
Clase · Estable · agnara_http
Aplicación ASGI 3 compilada, con sus planes y exposiciones. Se obtiene con Http.compile().
HttpApplication.__call__ Método
async __call__(
scope: _Scope,
receive: Callable[[], Any],
send: Callable[[Any], Any],
) -> NoneAtiende una conexión ASGI de tipo http o lifespan.
scope- Ámbito de conexión que recibe la aplicación ASGI.
receive- Callable ASGI para recibir mensajes.
send- Callable ASGI para enviar mensajes.
HttpApplication.surface Propiedad
Identidad de esta aplicación HTTP compilada. SurfaceId
HttpApplication.exposures Propiedad
Registros neutrales de la superficie para agregación e introspección. SurfaceCompilation[Any]
HttpApplication.plans Propiedad
Planes compilados en orden de declaración. tuple[ExecutionPlan, ...]
HttpApplication.openapi Método
openapi() -> dict[str, Any]
Genera un documento OpenAPI 3.2 a partir de la superficie compilada.
HttpDefinitionError
Excepción · Estable · agnara_http
La composición HTTP es inválida, ambigua o se intentó después de cerrar las declaraciones.
HttpDocumentation
Clase · Estable · agnara_http
Configuración independiente para publicar el esquema OpenAPI y cada interfaz de documentación.
HttpDocumentation(
schema: OpenApiSchema | None = <factory>,
swagger: SwaggerUI | None = <factory>,
scalar: Scalar | None = None,
redoc: ReDoc | None = None,
) -> NoneParámetros
schema- Configuración de publicación de JSON OpenAPI.
swagger- Configuración opcional de Swagger UI.
scalar- Configuración opcional de Scalar.
redoc- Configuración opcional de ReDoc.
Atributos
schema: OpenApiSchema | None- Configuración de publicación de JSON OpenAPI.
swagger: SwaggerUI | None- Configuración opcional de Swagger UI.
scalar: Scalar | None- Configuración opcional de Scalar.
redoc: ReDoc | None- Configuración opcional de ReDoc.
HttpExplorer
Clase · Estable · agnara_http
Configuración del Explorer de solo lectura. Sirve una instantánea filtrada según la identidad y la visibilidad.
HttpExplorer(
snapshot: IntrospectionSnapshot,
visibility: DiscoveryVisibility,
principals: Callable[[_Scope], Principal | None],
path: str = '/agnara',
challenge: str | None = None,
allow_anonymous: bool = False,
cache_control: str = 'private, no-store',
) -> NoneParámetros
snapshot- Instantánea de introspección que se filtra o publica.
visibility- Regla de visibilidad y selección de campos para la instantánea.
principals- Función del host que resuelve una identidad verificada desde el contexto del transporte.
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
challenge- Desafío de autenticación HTTP que el host configura para las respuestas aplicables.
allow_anonymous- Permite que la superficie atienda lectores sin principal autenticado, sujetos a la política de visibilidad.
cache_control- Valor de la política HTTP de caché.
El host proporciona principals para identificar al lector. El filtro se aplica antes de entregar datos. Su caché es privada y no persistente por omisión.
Atributos
snapshot: IntrospectionSnapshot- Instantánea de introspección que se filtra o publica.
visibility: DiscoveryVisibility- Regla de visibilidad y selección de campos para la instantánea.
principals: Callable[[_Scope], Principal | None]- Función del host que resuelve una identidad verificada desde el contexto del transporte.
path: str- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
challenge: str | None- Desafío de autenticación HTTP que el host configura para las respuestas aplicables.
allow_anonymous: bool- Permite que la superficie atienda lectores sin principal autenticado, sujetos a la política de visibilidad.
cache_control: str- Valor de la política HTTP de caché.
OpenApiInfo
Clase · Estable · agnara_http
Metadatos del documento OpenAPI generado.
OpenApiInfo(
title: str,
version: str,
*,
summary: str | None = None,
description: str | None = None,
) -> NoneParámetros
title- Título que puede mostrarse al lector.
version- Versión anunciada por el documento, agente, servidor o formato.
summary- Resumen breve que se publica para el documento o la operación.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
OpenApiInfo.title Propiedad
Título que puede mostrarse al lector. str
OpenApiInfo.version Propiedad
Versión anunciada por el documento, agente, servidor o formato. str
OpenApiInfo.summary Propiedad
Resumen breve que se publica para el documento o la operación. str | None
OpenApiInfo.description Propiedad
Descripción que acompaña a la declaración. Su publicación depende de la superficie. str | None
OpenApiOperation
Clase · Estable · agnara_http
Metadatos y habilitación explícita de una operación en OpenAPI.
OpenApiOperation(
*,
summary: str | None = None,
publish_description: bool = False,
tags: Sequence[str] = (),
deprecated: bool = False,
) -> NoneParámetros
summary- Resumen breve que se publica para el documento o la operación.
publish_description- Autoriza publicar la descripción declarada de la capacidad para esa operación.
tags- Etiquetas publicadas junto a una operación o habilidad.
deprecated- Marca la operación como obsoleta en OpenAPI.
OpenApiOperation.summary Propiedad
Resumen breve que se publica para el documento o la operación. str | None
OpenApiOperation.publish_description Propiedad
Autoriza publicar la descripción declarada de la capacidad para esa operación. bool
Etiquetas publicadas junto a una operación o habilidad. tuple[str, ...]
OpenApiOperation.deprecated Propiedad
Marca la operación como obsoleta en OpenAPI. bool
OpenApiSchema
Clase · Estable · agnara_http
Configura la ruta estática que publica el documento JSON de OpenAPI.
OpenApiSchema(path: str = '/openapi.json') -> None
Parámetros
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
Atributos
path: str- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
ReDoc
Clase · Estable · agnara_http
Configura la página integrada de documentación ReDoc de solo lectura.
ReDoc(path: str = '/redoc', assets: DocumentationAssets = <factory>) -> None
Parámetros
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
assets- Configuración de recursos que carga la interfaz.
Atributos
path: str- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
assets: DocumentationAssets- Configuración de recursos que carga la interfaz.
Scalar
Clase · Estable · agnara_http
Configura la página integrada de documentación Scalar y su modo interactivo.
Scalar(
path: str = '/scalar',
try_it: bool = False,
assets: DocumentationAssets = <factory>,
) -> NoneParámetros
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
try_it- Habilita las llamadas interactivas desde la interfaz de documentación.
assets- Configuración de recursos que carga la interfaz.
Atributos
path: str- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
try_it: bool- Habilita las llamadas interactivas desde la interfaz de documentación.
assets: DocumentationAssets- Configuración de recursos que carga la interfaz.
SwaggerUI
Clase · Estable · agnara_http
Configura Swagger UI y su modo interactivo.
SwaggerUI(
path: str = '/docs',
try_it: bool = False,
assets: DocumentationAssets = <factory>,
) -> NoneParámetros
path- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
try_it- Habilita las llamadas interactivas desde la interfaz de documentación.
assets- Configuración de recursos que carga la interfaz.
Atributos
path: str- Ruta HTTP de la superficie o ubicación del valor inválido en un error de validación.
try_it: bool- Habilita las llamadas interactivas desde la interfaz de documentación.
assets: DocumentationAssets- Configuración de recursos que carga la interfaz.
10. Adaptador MCP
agnara_mcp · 20 exportaciones
Compila herramientas de una aplicación. El host autentica el transporte, aporta el mapeo de identidad y cierra el cliente antes del contenedor. Descubrimiento e invocación comparten una tabla compilada.
Guía relacionada · MCP_TOOLS.md
MCP_PROTOCOL_VERSION · MCP_PYTHON_SDK_VERSION · SUPPORTED_MCP_PROTOCOL_VERSIONS · FrozenMcpTools · Mcp · McpAuthenticatedIdentity · McpAuthorization · McpAuthorizationDefinitionError · McpInteractionProjectionError · McpInvocationDefinitionError · McpPrincipalMapper · McpResultProjectionError · McpToolDefinitionError · McpToolExposure · McpToolInvoker · build_mcp_discovery_server · build_mcp_server · project_mcp_interaction_required · project_mcp_result · project_mcp_tools
MCP_PROTOCOL_VERSION
Constante · Estable · agnara_mcp
Revisión principal del protocolo MCP servida por este adaptador.
MCP_PROTOCOL_VERSION = '2026-07-28'
MCP_PYTHON_SDK_VERSION
Constante · Estable · agnara_mcp
Versión exacta del SDK Python MCP utilizada por el adaptador.
MCP_PYTHON_SDK_VERSION = '2.2.0'
SUPPORTED_MCP_PROTOCOL_VERSIONS
Constante · Estable · agnara_mcp
Tupla de revisiones MCP admitidas.
SUPPORTED_MCP_PROTOCOL_VERSIONS = ('2026-07-28',)Clase · Estable · agnara_mcp
Colección inmutable de herramientas MCP compiladas en orden de registro.
FrozenMcpTools(exposures: tuple[McpToolExposure, ...]) -> None
Parámetros
exposures- Colección de destinos compilados de la superficie o del proyecto.
__getitem__(name: str) -> McpToolExposure
Busca un elemento por su clave.
name- Nombre lógico de la entidad que se declara, describe o publica.
__iter__() -> Iterator[str]
Recorre las claves de la colección.
__len__() -> int
Devuelve la cantidad de declaraciones o elementos de la colección.
Herramientas compiladas en orden de registro. tuple[McpToolExposure, ...]
Mcp
Clase · Estable · agnara_mcp
Declara herramientas MCP para capacidades de una aplicación y congela su registro para composición.
Mcp(app: Agnara, *, surface: str = 'default') -> None
Parámetros
app- Aplicación o contexto que posee las declaraciones.
surface- Identidad o nombre de la superficie que sirve la exposición.
Mcp.is_compiled Propiedad
Indica que se cerró el registro de herramientas. bool
Mcp.surface Propiedad
Identidad de esta superficie MCP para el registro de exposiciones. SurfaceId
tool(
capability: CapabilityDefinition | Callable[..., Any],
/,
*,
name: str | None = None,
) -> McpToolExposureVincula una capacidad declarada con un nombre de herramienta MCP.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
name- Nombre lógico de la entidad que se declara, describe o publica.
Mcp.compile Método
compile() -> FrozenMcpTools
Cierra el registro y devuelve una instantánea de herramientas reutilizable.
Mcp.compile_surface Método
compile_surface() -> SurfaceCompilation[FrozenMcpTools]
Devuelve el registro compilado de herramientas y sus exposiciones neutrales.
Mcp.__len__ Método
__len__() -> int
Devuelve la cantidad de declaraciones o elementos de la colección.
McpAuthenticatedIdentity
Clase · Estable · agnara_mcp
Datos de identidad verificados y saneados que recibe el mapeador MCP. El token sin procesar queda en el límite del host.
McpAuthenticatedIdentity(
client_id: str,
issuer: str | None,
subject: str | None,
resource: str | None,
scopes: frozenset[str],
) -> NoneParámetros
client_id- Identificador del cliente aportado por el verificador.
issuer- Identidad del emisor aportada por el verificador.
subject- Identidad del sujeto aportada por el verificador.
resource- Identidad del recurso que aporta el verificador MCP.
scopes- Permisos declarados por la capacidad o concedidos a una identidad verificada.
Atributos
client_id: str- Identificador del cliente aportado por el verificador.
issuer: str | None- Identidad del emisor aportada por el verificador.
subject: str | None- Identidad del sujeto aportada por el verificador.
resource: str | None- Identidad del recurso que aporta el verificador MCP.
scopes: frozenset[str]- Permisos declarados por la capacidad o concedidos a una identidad verificada.
McpAuthorization
Clase · Estable · agnara_mcp
Resuelve la identidad de la petición y filtra las herramientas visibles según sus permisos.
McpAuthorization(exposures: FrozenMcpTools, mapper: McpPrincipalMapper) -> None
Parámetros
exposures- Colección de destinos compilados de la superficie o del proyecto.
mapper- Función que convierte identidad MCP verificada en Principal.
El mapeador recibe datos saneados del verificador. Los parámetros de tools/call no conceden identidad o permisos.
Nombres de las exposiciones configuradas, en orden de declaración. tuple[str, ...]
McpAuthorization.principal Método
principal() -> Principal
Obtiene el principal de la petición a partir de la identidad que verificó el host.
discoverable_tool_names() -> frozenset[str]
Filtra las herramientas que el principal puede descubrir según sus permisos estáticos.
McpAuthorizationDefinitionError
Excepción · Estable · agnara_mcp
La composición de autorización MCP es inválida o incompatible con las herramientas.
McpInteractionProjectionError
Excepción · Estable · agnara_mcp
Un fallo que requiere interacción no puede proyectarse de manera segura a MCP.
McpInvocationDefinitionError
Excepción · Estable · agnara_mcp
La superficie de invocación MCP se configuró de manera incoherente.
McpPrincipalMapper
Protocolo · Estable · agnara_mcp
Protocolo invocable que transforma identidad MCP verificada en una identidad Principal de la aplicación.
McpPrincipalMapper.__call__ Método
__call__(identity: McpAuthenticatedIdentity, /) -> Principal
Transforma los datos saneados del verificador en un Principal de la aplicación.
identity- Identificador estable de la persona o servicio, o identidad verificada entregada al mapeador.
McpResultProjectionError
Excepción · Estable · agnara_mcp
El resultado canónico no puede representarse con seguridad como resultado de herramienta MCP.
Excepción · Estable · agnara_mcp
Una exposición MCP es inválida o ambigua.
Clase · Estable · agnara_mcp
Asocia un nombre válido de herramienta MCP con una capacidad neutral al transporte.
McpToolExposure(name: str, definition: CapabilityDefinition) -> None
Parámetros
name- Nombre lógico de la entidad que se declara, describe o publica.
definition- Declaración de la capacidad que se compila o expone.
Atributos
name: str- Nombre lógico de la entidad que se declara, describe o publica.
definition: CapabilityDefinition- Declaración de la capacidad que se compila o expone.
Clase · Estable · agnara_mcp
Resuelve tools/call contra una tabla inmutable y despacha al plan compilado.
McpToolInvoker(
exposures: FrozenMcpTools,
plans: Iterable[ExecutionPlan],
di_container: DIContainer,
*,
authorization: McpAuthorization | None = None,
timeout: float | None = None,
) -> NoneParámetros
exposures- Colección de destinos compilados de la superficie o del proyecto.
plans- Planes compilados que la superficie puede despachar o describir.
di_container- Contenedor que aporta los recursos de esta ejecución.
authorization- Resolución y filtrado de identidades para el servidor MCP.
timeout- Presupuesto de ejecución en segundos. None omite este límite explícito.
Nombres de las herramientas invocables en orden de declaración. tuple[str, ...]
async __call__(
ctx: ServerRequestContext[Any],
params: CallToolRequestParams,
) -> CallToolResult | InputRequiredResultAtiende tools/call con el contexto del SDK y despacha al plan autorizado.
ctx- Contexto de petición que entrega el SDK de MCP.
params- Parámetros de tools/call que suministra el SDK MCP.
build_mcp_discovery_server
Función · Estable · agnara_mcp
Construye un servidor del SDK oficial que permite descubrir herramientas de una instantánea.
build_mcp_discovery_server(
tools: Iterable[Tool],
*,
name: str,
version: str,
instructions: str | None = None,
authorization: McpAuthorization | None = None,
) -> Server[Any]Parámetros
tools- Descriptores de herramientas que se publican en MCP.
name- Nombre lógico de la entidad que se declara, describe o publica.
version- Versión anunciada por el documento, agente, servidor o formato.
instructions- Texto de instrucciones que el servidor MCP ofrece al cliente.
authorization- Resolución y filtrado de identidades para el servidor MCP.
build_mcp_server
Función · Estable · agnara_mcp
Construye un servidor del SDK oficial que descubre e invoca herramientas. El host coordina el cierre del cliente y del contenedor.
build_mcp_server(
exposures: FrozenMcpTools,
plans: Iterable[ExecutionPlan],
di_container: DIContainer,
*,
name: str,
version: str,
instructions: str | None = None,
authorization: McpAuthorization | None = None,
timeout: float | None = None,
) -> Server[Any]Parámetros
exposures- Colección de destinos compilados de la superficie o del proyecto.
plans- Planes compilados que la superficie puede despachar o describir.
di_container- Contenedor que aporta los recursos de esta ejecución.
name- Nombre lógico de la entidad que se declara, describe o publica.
version- Versión anunciada por el documento, agente, servidor o formato.
instructions- Texto de instrucciones que el servidor MCP ofrece al cliente.
authorization- Resolución y filtrado de identidades para el servidor MCP.
timeout- Presupuesto de ejecución en segundos. None omite este límite explícito.
project_mcp_interaction_required
Función · Estable · agnara_mcp
Proyecta una solicitud canónica compatible de confirmación al formulario de interacción MCP.
project_mcp_interaction_required(failure: Failure) -> InputRequiredResult
Parámetros
failure- Fallo canónico que explica la interrupción o se proyecta al adaptador.
project_mcp_result
Función · Estable · agnara_mcp
Convierte un resultado canónico en la respuesta MCP correspondiente. No ejecuta la capacidad.
project_mcp_result(
outcome: CanonicalResult[object],
) -> CallToolResult | InputRequiredResultParámetros
outcome- Desenlace de la invocación o resultado canónico que se proyecta.
Función · Estable · agnara_mcp
Genera descriptores de herramientas del SDK desde las exposiciones y sus planes. Devuelve datos independientes de las tablas compiladas.
project_mcp_tools(
exposures: FrozenMcpTools,
plans: Iterable[ExecutionPlan],
) -> tuple[Tool, ...]Parámetros
exposures- Colección de destinos compilados de la superficie o del proyecto.
plans- Planes compilados que la superficie puede despachar o describir.
11. Adaptador A2A provisional
agnara_a2a · 8 exportaciones
El perfil publicado cubre una habilidad de resultado completo. Sus ocho nombres son provisionales y pueden cambiar dentro de la línea 1.x tras revisión.
Guía relacionada · A2A_SERVICE.md
A2A_PROTOCOL_VERSION · A2A_PYTHON_SDK_VERSION · SUPPORTED_A2A_PROTOCOL_VERSIONS · A2a · A2aAgentCard · A2aDefinitionError · A2aSkillExposure · build_a2a_app
A2A_PROTOCOL_VERSION
Constante · Provisional · agnara_a2a
Versión de protocolo anunciada por el perfil A2A publicado.
A2A_PROTOCOL_VERSION = '1.0'
A2A_PYTHON_SDK_VERSION
Constante · Provisional · agnara_a2a
Versión exacta del SDK Python usada por el adaptador A2A.
A2A_PYTHON_SDK_VERSION = '1.3.0'
SUPPORTED_A2A_PROTOCOL_VERSIONS
Constante · Provisional · agnara_a2a
Tupla de versiones de protocolo admitidas por el perfil A2A.
SUPPORTED_A2A_PROTOCOL_VERSIONS = ('1.0',)A2a
Clase · Provisional · agnara_a2a
Declara una superficie A2A provisional con una sola capacidad de resultado completo, publicada como habilidad.
A2a(app: Agnara, *, surface: str = 'default') -> None
Parámetros
app- Aplicación o contexto que posee las declaraciones.
surface- Identidad o nombre de la superficie que sirve la exposición.
El ejemplo de esta edición ejecuta el SDK oficial en proceso. Las tareas A2A y el streaming quedan fuera del perfil de esta edición.
A2a.is_compiled Propiedad
Indica que se cerró el registro de habilidades. bool
A2a.surface Propiedad
Identidad de esta superficie A2A para el registro de exposiciones. SurfaceId
A2a.skill Método
skill(
capability: CapabilityDefinition | Callable[..., Any],
/,
*,
id: str,
name: str,
description: str,
tags: tuple[str, ...],
) -> A2aSkillExposureDeclara la única habilidad y la vincula a una capacidad registrada.
capability- Capacidad seleccionada o descriptor que evalúa la regla.
id- Identificador del registro. Su tipo depende de la entidad.
name- Nombre lógico de la entidad que se declara, describe o publica.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
tags- Etiquetas publicadas junto a una operación o habilidad.
A2a.compile Método
compile() -> A2aSkillExposure
Cierra las declaraciones y devuelve la exposición de habilidad.
A2a.compile_surface Método
compile_surface() -> SurfaceCompilation[A2aSkillExposure]
Devuelve la habilidad compilada con el registro de exposición neutral.
A2aAgentCard
Clase · Provisional · agnara_a2a
Metadatos del agente para su Agent Card pública sin firma.
A2aAgentCard(name: str, description: str, version: str) -> None
Parámetros
name- Nombre lógico de la entidad que se declara, describe o publica.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
version- Versión anunciada por el documento, agente, servidor o formato.
Atributos
name: str- Nombre lógico de la entidad que se declara, describe o publica.
description: str- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
version: str- Versión anunciada por el documento, agente, servidor o formato.
A2aDefinitionError
Excepción · Provisional · agnara_a2a
La configuración no satisface el perfil A2A de resultado completo.
A2aSkillExposure
Clase · Provisional · agnara_a2a
Une una capacidad declarada con la única habilidad que publica una superficie A2A.
A2aSkillExposure(
definition: CapabilityDefinition,
id: str,
name: str,
description: str,
tags: tuple[str, ...],
) -> NoneParámetros
definition- Declaración de la capacidad que se compila o expone.
id- Identificador del registro. Su tipo depende de la entidad.
name- Nombre lógico de la entidad que se declara, describe o publica.
description- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
tags- Etiquetas publicadas junto a una operación o habilidad.
Atributos
definition: CapabilityDefinition- Declaración de la capacidad que se compila o expone.
id: str- Identificador del registro. Su tipo depende de la entidad.
name: str- Nombre lógico de la entidad que se declara, describe o publica.
description: str- Descripción que acompaña a la declaración. Su publicación depende de la superficie.
tags: tuple[str, ...]- Etiquetas publicadas junto a una operación o habilidad.
build_a2a_app
Función · Provisional · agnara_a2a
Construye la aplicación ASGI que sirve la Agent Card y la habilidad con el plan compilado. El host aporta identidad y es propietario del ciclo de vida.
build_a2a_app(
exposure: A2aSkillExposure,
plans: Iterable[ExecutionPlan],
di_container: DIContainer,
*,
card: A2aAgentCard,
url: str,
principals: _PrincipalResolver,
challenge: str,
timeout: float = 30.0,
max_body_bytes: int = 1048576,
card_cache_control: str | None = None,
) -> Callable[[_Scope, _Receive, _Send], Awaitable[None]]Parámetros
exposure- Exposición compilada que selecciona la capacidad servida.
plans- Planes compilados que la superficie puede despachar o describir.
di_container- Contenedor que aporta los recursos de esta ejecución.
card- Metadatos del agente que se publicarán en la Agent Card.
url- URL pública que se anuncia para la interfaz A2A.
principals- Función del host que resuelve una identidad verificada desde el contexto del transporte.
challenge- Desafío de autenticación HTTP que el host configura para las respuestas aplicables.
timeout- Presupuesto de ejecución en segundos. None omite este límite explícito.
max_body_bytes- Tamaño máximo del cuerpo admitido en bytes.
card_cache_control- Valor de Cache-Control de la Agent Card.
12. Interfaz de línea de comandos
agnara_cli · 4 exportaciones
La CLI genera estructuras de proyecto y permite inspeccionar composiciones. Usa agnara --help para ver los comandos instalados y agnara COMANDO --help para sus opciones.
Guía relacionada · CLI_SPEC.md
EXIT_FAILED · EXIT_OK · EXIT_USAGE · main
EXIT_FAILED
Constante · Estable · agnara_cli
Código de salida que indica que un comando no pudo completarse.
EXIT_FAILED = 1
EXIT_OK
Constante · Estable · agnara_cli
Código de salida de un comando completado correctamente.
EXIT_OK = 0
EXIT_USAGE
Constante · Estable · agnara_cli
Código de salida para uso incorrecto de la CLI.
EXIT_USAGE = 2
main
Función · Estable · agnara_cli
Ejecuta un comando de la CLI y devuelve su código de salida.
main(argv: Sequence[str] | None = None) -> int
Parámetros
argv- Argumentos de la CLI sin el nombre del ejecutable. Con None usa los argumentos del proceso.
Para un proceso nuevo se puede ejecutar python -m agnara_cli --help. EXIT_OK, EXIT_FAILED y EXIT_USAGE documentan los códigos de salida.
13. Telemetría OpenTelemetry
agnara_telemetry · 2 exportaciones
Los hooks observan la ejecución de la capacidad. La aplicación aporta el medidor o trazador y gestiona su ciclo de vida y sus exportadores.
Guía relacionada · TELEMETRY.md
OpenTelemetryMetricsHook · OpenTelemetryTracingHook
OpenTelemetryMetricsHook
Clase · Estable · agnara_telemetry
Hook que registra medidas al terminar una invocación con el medidor suministrado por el host.
OpenTelemetryMetricsHook(meter: opentelemetry.metrics.Meter) -> None
Parámetros
meter- Medidor OpenTelemetry suministrado por el host.
OpenTelemetryMetricsHook.on_invocation_start Método
on_invocation_start(event: InvocationStartEvent) -> None
Acepta el evento inicial sin mantener estado de correlación.
event- Evento de telemetría entregado al observador.
OpenTelemetryMetricsHook.on_invocation_terminal Método
on_invocation_terminal(event: InvocationTerminalEvent) -> None
Registra la duración y el desenlace con el medidor configurado.
event- Evento de telemetría entregado al observador.
OpenTelemetryTracingHook
Clase · Estable · agnara_telemetry
Hook que abre un span al comenzar la invocación y lo cierra con el evento terminal correspondiente.
OpenTelemetryTracingHook(tracer: opentelemetry.trace.Tracer) -> None
Parámetros
tracer- Trazador OpenTelemetry suministrado por el host.
OpenTelemetryTracingHook.on_invocation_start Método
on_invocation_start(event: InvocationStartEvent) -> None
Abre un span y lo establece como actual para las invocaciones anidadas.
event- Evento de telemetría entregado al observador.
OpenTelemetryTracingHook.on_invocation_terminal Método
on_invocation_terminal(event: InvocationTerminalEvent) -> None
Cierra el span asociado si existe un inicio correspondiente.
event- Evento de telemetría entregado al observador.
14. Espacio reservado para eventos
agnara_events · 0 exportaciones
La distribución agnara-events 1.0.4 instala este espacio de nombres con cero exportaciones públicas. El consumo de eventos y la ejecución durable se investigan por separado.
Guía relacionada · MATURITY.md
15. Índice alfabético
Las entradas enlazan a los nombres importables. Para un método o atributo, abre la ficha de su clase o usa la búsqueda del HTML.
16. Versión y fuentes
Agnara 1.0.4 se publicó el 10 de noviembre de 2026. Las firmas y los valores de constantes se comprobaron en los siete paquetes instalados con CPython 3.14.4. Los nombres coinciden con el manifiesto de la etiqueta v1.0.4.