Concepts

Architecture

The layer boundaries and runtime-selection model for Agentic Fabric.

This page records the local plan for agentic-fabric. It is the source of truth for agent runtime architecture in this repository.

Boundary

agentic-fabric owns agent and fabric agent orchestration:

  • discovery and manifest loading
  • universal fabric agent composition
  • runner adapters for optional agent frameworks
  • A2A Agent Cards, JSON-RPC task execution, and MCP tool servers
  • tool resolution for built-in, MCP-style, fully qualified, and vendor-backed tools
  • agent-facing tool catalogs built from vendor-fabric capability metadata
  • agent capability dispatch over the data and vendor layers
  • pytest support for agent runtime tests

extended-data owns base data primitives, logging, input handling, files, redaction, and generic workflows. vendor-fabric owns vendor API connectors, provider-backed sync, SecretSync Python facade/capability surfaces, provider capability metadata, and provider dispatch.

AgenticData

AgenticData extends the vendor layer in the same way VendorData extends ExtendedData. The full-stack inheritance line is:

ExtendedData -> VendorData -> AgenticData

AgenticData owns agent runtime context. It does not reimplement data containers or provider sync. Those behaviors come from the required vendor-fabric layer; provider-specific SDKs remain optional and lazy.

from agentic_fabric import AgenticData


session = AgenticData({"task": "summarize"})
session.use_runtime("langgraph", strict=False)

That shape lets the agent layer carry data, provider, and runtime context together:

session.register_fabric_agent("repo_summarizer", fabric_agent_config)
result = session.run_fabric_agent("repo_summarizer", repo="jbcom/extended-data")

Agent Capability Registry

Agent and runtime capabilities should use normal Python mechanisms:

  • typing.Protocol for runner and tool contracts
  • abstract base classes for shared runner behavior
  • @agent_capability(...) or @tool_capability(...) decorators on concrete runtime/tool methods
  • __init_subclass__ to collect capability metadata through inheritance
  • read-only capability mappings for inspection and deterministic dispatch
  • __getattr__ only as a convenience over declared capabilities
  • __dir__ for autocomplete and developer inspection

The implementation lives in agentic_fabric.capabilities:

  • @agent_capability(...)
  • @runtime_capability(...)
  • @tool_capability(...)
  • AgentCapabilitySpec
  • AgentCapabilityProviderMixin

Do not use custom dunder capability names. The capability registry is plain Python metadata collected at class creation.

Runtime Selection

Runtime frameworks are optional and should be discovered lazily. The core package should import without CrewAI, LangGraph, Strands, or vendor SDKs being imported eagerly.

Runtime metadata lives in agentic_fabric.runners.registry. The public compatibility API remains in agentic_fabric.core.decomposer: detect_framework(), get_runner(), get_available_frameworks(), get_framework_info(), is_framework_available(), compose_fabric_agent(), run_fabric_agent_auto(), get_cli_runner(), get_available_cli_runners(), and is_cli_runner_available().

Runtime selection follows this precedence:

  1. an explicit runtime argument from the caller
  2. a runtime already active on AgenticData
  3. a runtime required by the fabric agent manifest or framework-specific config directory
  4. the first installed runtime in documented priority order
  5. a clear unavailable-runtime error with install guidance

Manifest-required runtimes are also compatibility constraints. If a caller explicitly requests langgraph for a fabric agent that requires crewai, or an active runtime conflicts with that requirement, AgenticData raises a configuration error rather than silently selecting another framework.

Vendor Tooling

Vendor-backed tools should go through AgenticData, VendorData, and vendor-fabric capabilities. Agent code should not call cloud SDKs directly. Agent tools that need repository files, Slack messages, Vault secrets, or S3 objects should route through provider capabilities declared by vendor-fabric.

Lazy vendor tool references are supported with vendor://provider/operation and vendor:provider:operation names. When vendor-fabric is installed, AgenticData.vendor_tools() reads VendorData.capabilities() and returns lazy agent-facing wrappers for those provider operations.

Protocol Surfaces

A2A and MCP are agent-side interfaces, so their cards, routes, task events, tool schemas, transports, and protocol errors live here. They lower calls into AgenticData and public vendor-fabric capabilities. They do not own credentials, connector construction, capability dispatch, or provider IO.

The A2A surface advertises only the protocol binding it actually implements: version 1.0 JSON-RPC. The MCP surface targets SDK 2.x and returns complete typed results with structured content plus a text fallback. Both keep protocol SDK imports lazy behind their matching extras.

Testing Package

pytest-agentic-fabric is a sibling package in this repository. It provides runtime availability fixtures, framework mocking helpers, minimal fabric agent/workspace fixtures, credential skip fixtures, and opt-in E2E controls.

Provider fixtures belong in pytest-vendor-fabric. Base data fixtures belong in pytest-extended-data.

Validation Contract

Every public behavior needs tests and docs in the same change. Python 3.11, 3.12, 3.13, and 3.14 must pass without skipped missing interpreters.

Built withSourcey
Edit this page